| 1 | # clover's snow globe |
| 2 | |
| 3 | This codebase contains declarative configuration to run my home server, a |
| 4 | computer sitting in my closet used daily to power my activities. It first and |
| 5 | foremost 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, |
| 7 | from Jellyfin and Navidrome for media consumption to git hosting and render |
| 8 | farms. |
| 9 | |
| 10 | The system is built out of a NixOS base (just to install the system itself), |
| 11 | using Podman containers scheduled by Nomad and virtual machines to run the |
| 12 | services. Changes automatically get a staging deployment on Snow Globe for |
| 13 | testing and review. Production promotion is a separate, explicit step. |
| 14 | |
| 15 | [paper clover]: https://paperclover.net |
| 16 | |
| 17 | ## change → preview → review |
| 18 | |
| 19 | The deployment tool defaults to Snow Globe at `root@10.0.0.1:22`. |
| 20 | |
| 21 | ```sh |
| 22 | python3 tools/deploy.py stage shale |
| 23 | python3 tools/deploy.py stage dashboard |
| 24 | ``` |
| 25 | |
| 26 | These upload working files and print the preview URL. Service previews use |
| 27 | separate ZFS storage; the dashboard preview uses disposable accounts and files, |
| 28 | with read-only observations of the real host. Test the app and keep its preview |
| 29 | available for review. Repeating the command updates that preview. |
| 30 | |
| 31 | After approval, commit the reviewed changes on `main` and run |
| 32 | `python3 tools/deploy.py prod`. The release workflow backs up state, activates |
| 33 | the release, and checks production health. Single-writer services can have a |
| 34 | brief interruption. Code rollback and data restore are separate operations. |
| 35 | |
| 36 | GPU AI changes are tested directly in production. VM integration uses disposable |
| 37 | guests on the real machine. Most other work follows the preview workflow above; |
| 38 | isolated host testing is documented in [tools/rehearsal.md](tools/rehearsal.md). |
| 39 | The complete agent workflow is in [AGENTS.md](AGENTS.md). |
| 40 | |
| 41 | ## filesystem layout |
| 42 | |
| 43 | The computer mounts the ZFS root dataset under `/srv`, meaning "server," loosely |
| 44 | following the linux convention. Within, it's a unique structure: |
| 45 | |
| 46 | ``` |
| 47 | srv/ |
| 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 | |
| 75 | Media is its own dataset so it can be snapshotted independently of personal |
| 76 | data. Personal files share a dataset to allow fast moves between top-level |
| 77 | folders; services use separate datasets for copy-on-write previews. No automatic |
| 78 | snapshot retention policy is configured. Hardware, encryption, permissions, and |
| 79 | recovery boundaries are documented in [tools/snowglobe-hardware.md](tools/snowglobe-hardware.md). |