1# clover's snow globe
2
3This codebase contains declarative configuration to run my home server, a
4computer sitting in my closet used daily to power my activities. It first and
5foremost acts as a file store for my ongoing and archived projects for
6[paper clover]. Secondly, it contains a ton of apps for me and friends to use,
7from Jellyfin and Navidrome for media consumption to git hosting and render
8farms.
9
10The system is built out of a NixOS base (just to install the system itself),
11using Podman containers scheduled by Nomad and virtual machines to run the
12services. Changes automatically get a staging deployment on Snow Globe for
13testing and review. Production promotion is a separate, explicit step.
14
15[paper clover]: https://paperclover.net
16
17## change → preview → review
18
19The deployment tool defaults to Snow Globe at `root@10.0.0.1:22`.
20
21```sh
22python3 tools/deploy.py stage shale
23python3 tools/deploy.py stage dashboard
24```
25
26These upload working files and print the preview URL. Service previews use
27separate ZFS storage; the dashboard preview uses disposable accounts and files,
28with read-only observations of the real host. Test the app and keep its preview
29available for review. Repeating the command updates that preview.
30
31After approval, commit the reviewed changes on `main` and run
32`python3 tools/deploy.py prod`. The release workflow backs up state, activates
33the release, and checks production health. Single-writer services can have a
34brief interruption. Code rollback and data restore are separate operations.
35
36GPU AI changes are tested directly in production. VM integration uses disposable
37guests on the real machine. Most other work follows the preview workflow above;
38isolated host testing is documented in [tools/rehearsal.md](tools/rehearsal.md).
39The complete agent workflow is in [AGENTS.md](AGENTS.md).
40
41## filesystem layout
42
43The computer mounts the ZFS root dataset under `/srv`, meaning "server," loosely
44following the linux convention. Within, it's a unique structure:
45
46```
47srv/
48+--- clover/ [dataset] user-data storage, what I mount as /Volumes/clover
49 +--- Archive/<year> personal archive. one folder per year, scrambled within.
50 +--- Asset/ resources, sample packs, audio plugins, stock videos
51 +--- Blender/
52 +--- Font/
53 +--- Samples/
54 +--- Texture/
55 +--- Video/
56 +--- Documents/
57 +--- Project/ currently active project files
58 +--- Media/ [dataset] files from the world-wide-web. managed partially manually
59 +--- jellyfin/
60 +--- mirror/
61 +--- music/ (used by navidrome)
62 +--- music-intake/ (to be manually indexed)
63 +--- seedbox/
64 +--- vm/ (virtual machine images)
65 +--- Published/ source of truth for `paperclover.net/file`
66+--- prod/ [dataset] production application data
67 +--- shale/ [dataset] (each service is its own dataset)
68 +--- ...
69+--- staging/ staging deployments use this space for temporary clones
70 +--- postgres-9f06f74b/ [dataset]
71+--- vm/ [dataset] virtual machines
72 +--- clover-sandbox/ [dataset]
73```
74
75Media is its own dataset so it can be snapshotted independently of personal
76data. Personal files share a dataset to allow fast moves between top-level
77folders; services use separate datasets for copy-on-write previews. No automatic
78snapshot retention policy is configured. Hardware, encryption, permissions, and
79recovery boundaries are documented in [tools/snowglobe-hardware.md](tools/snowglobe-hardware.md).