nimmo/nixos-config
nimmo/nixos-config
Watch
1
0
Fork
You've already forked nixos-config
 0
Code Issues 15 Pull requests Wiki Activity Actions
Page: 15 Storage and Data Map
Pages
00 Documentation Map and Scope 00 Documentation Standards 00 Start Here and Governance 10 System Atlas 11 Fleet Overview 12 Host Inventory 13 Service Catalogue 14 Network and Access Topology 15 Storage and Data Map 16 Automation and Control Plane 20 Architecture Decisions 21 ADR 001 Electra Hardware Specialisations 22 ADR 002 Workload Placement 23 ADR 003 Network Exposure 23 Project Tracking 24 ADR 004 Engram Durable Agent Memory 24 Security Baseline 25 ADR 005 Auto Update Control Plane 26 ADR 006 Scoped Secret Files 30 Operations and Runbooks 31 Routine Fleet Operations 32 Safe Testing and Deployment 33 Host Provisioning 34 Monitoring and Service Investigation 35 Backup Verification and Partial Restore 36 Full Host Recovery 37 Electra Boot Trust Recovery 38 Secret Editing and Recipient Rotation 39 Auto Update Incident Response 39a Service Migration and Cutover 39b Wrapper Repository Packaging 40 Engineering Handbook 41 Repository Structure and Import Chain 42 Configuration Ownership Boundaries 43 Adding Packages and Flake Inputs 44 Adding a Module or Profile 45 Adding a Host 46 Adding or Migrating a Service 47 Testing and CI Contracts 48 Secrets Implementation Conventions 49 Documentation Maintenance 50 NixOS Learning Path 51 Guided Repository Tour 52 Nix Language Essentials 53 Declarative Configuration Store and Generations 54 Flakes and Inputs 55 NixOS Modules and Option Merging 56 SpecialArgs and Home Manager Argument Flow 57 Electra Specialisations Worked Example 58 Nix Troubleshooting Primer 90 Historical Material 91 Electra Secure Boot Hardening Record Home
3 15 Storage and Data Map
Nimmo edited this page 2026-09-14 07:34:27 +01:00
Table of contents

Storage and Data Map

  • Type: Reference
  • Status: Current
  • Scope: Local filesystems, service state, databases, NAS mounts, snapshots, and backup intent
  • Canonical sources: Host disko.nix files, host filesystem declarations, service data paths, composed nixosConfig.backup values, modules/services/backrest.nix, and modules/services/postgresql-backup.nix
  • Last verified: Source commit 937e7fd02aad450a006b49f592c156e75888db7a (2026-09-14); earlier composed backup options evaluated on 2026-09-12, with the new Vega ytdl-sub contribution checked in source
  • Review triggers: Disko or mount changes, service-state moves, database placement changes, NAS export changes, backup/snapshot policy changes, or restore testing

This page identifies where authoritative data lives and which mechanism is expected to protect it. A mount point is not proof of ownership, a Btrfs subvolume is not automatically a snapshot, and a local logical dump is not an off-host backup.

Data classes

Class Meaning Typical examples
Authoritative local state The host has the primary copy required to restore a service PostgreSQL, BookStack files, Trilium SQLite state, Paperless files, container volumes
Authoritative external state The primary copy belongs to infrastructure outside this repository NAS media, Immich library, shared appdata
Derived or replaceable data Can be rebuilt, repulled, or regenerated from another authority Nix store, Docker images, Attic cache objects, search indexes, downloaded models
Staging data Incomplete or intermediate work where loss may be acceptable but must not be mistaken for a backup SABnzbd partial downloads, music incoming directory, Tdarr transcode cache
Recovery artefact Exists specifically to recover another data source PostgreSQL logical dumps, Btrfs snapshots, restic repository snapshots

Local disk layouts

Host Declarative layout Data-bearing distinctions
Electra Two NVMe devices; LUKS-backed Btrfs plus encrypted swap Root disk has /, /home, and /run/media/models; second disk has /run/media/snapshots, /run/media/games, and 50 GiB hibernation swap. TPM enrolment is a post-install action, not created by Disko
Lena One NVMe Btrfs filesystem Separate /, /home, /nix, and /var/log subvolumes; no swap partition is declared in Disko
Vega OS NVMe with 16 GiB swap and Btrfs subvolumes Separate /, /home, /nix, /var/lib/docker, /srv/stacks, /srv/services, and /var/log. A second SSD, managed outside Disko, supplies /mnt/storage and /mnt/partial and is intended to survive OS reprovisioning
Lyra OS NVMe with 16 GiB swap and Btrfs subvolumes Separate /, /home, /nix, Docker, stacks, services, models, and logs; /srv/models isolates replaceable Ollama model data
Cosmos Proxmox virtual disk with Btrfs Separate /, /home, /nix, /var/log, and /var/lib/postgresql; no swap declared
Chaos Proxmox virtual disk with Btrfs Separate /, /home, /nix, /var/log, /var/lib/docker, and /srv/stacks; no swap declared

Only Electra's current Disko specification declares storage encryption. That is a statement about repository configuration, not an audit of encryption beneath Proxmox, the NAS, or other external storage layers.

Nova's staged specification proposes one NVMe Btrfs system disk with separate root, home, Nix, log, and Docker subvolumes. It is future intent and is excluded from the active fleet tables.

NAS-backed mounts

The external member mass-storage.mesh (10.10.0.5) is the authority for these NFS exports:

Export Consumers and mount points Access and purpose
/volume1/media Vega and Lyra at /mnt/media; Vega also at /srv/media; Chaos at /srv/media Shared media library. Usually read-only for consumers, but Vega's Navidrome playlist use, ytdl-sub output, and Tdarr/SABnzbd/slskd workflows require selected writable mounts
/volume1/appdata Vega and Lyra at /mnt/appdata; Lyra Redview mounts the ancestor at /var/lib/redview/media Shared application/media working data, including Tdarr paths and Redview content
/volume1/docker/tdarr Vega and Lyra at /mnt/tdarr Writable shared transcode cache; staging/derived rather than primary application state
/volume1/immich/libraries Lyra at /mnt/immich Authoritative Immich media library
/volume1/nix-cache Vega and Lyra at /srv/attic/storage Attic cache objects; replaceable cache data rather than unique source data

These are hard NFS 4.1 mounts ordered after network and, where enabled, Nebula. Most service units also require their mount before starting so an unavailable NAS does not turn an empty local directory into a false library. nofail is used for selected mounts so a missing NAS does not necessarily prevent the host from booting.

Backrest uses --one-file-system. A backed-up local parent does not traverse into a nested NFS mount. For example, Lyra's /var/lib/redview is included but the NFS filesystem mounted below /var/lib/redview/media is not copied into that restic snapshot.

Database authority

Vega PostgreSQL

Vega's active application cluster lives at /mnt/storage/postgresql. It listens on loopback, the Nebula address, and one dedicated Docker bridge. Its declared database set includes Immich, FreshRSS, Paperless, Attic, Engram Cloud, and retained application databases.

The backup timer creates daily compressed plain-SQL dumps, a role/global dump, and a manifest under /mnt/storage/postgresql-backups, retaining seven days locally. The dump is the appropriate portable recovery artefact; copying a live PostgreSQL data directory is not a substitute.

Cosmos PostgreSQL

Cosmos stores its cluster on the dedicated /var/lib/postgresql Btrfs subvolume. It declares a Paperless database and can contain databases restored during its migration. The current Paperless application configuration points to Vega, so the same database name on Cosmos must not be assumed to be the current application authority.

Cosmos creates the same form of daily logical dumps under /var/backups/postgresql. Unlike Vega's dump directory, this path is included in the host's Backrest plan.

BookStack MariaDB

BookStack stores application files under /mnt/storage/bookstack but uses the system MariaDB data directory for its database. The application directory is in Backrest; no MariaDB logical dump or MySQL data path is currently declared. Restoring only the backed-up BookStack path is therefore not a complete restore.

Effective Backrest coverage

Backrest is enabled on every registered host because each current host requests at least its primary user's home directory. It runs as root, binds its UI to 127.0.0.1:9898, and sends encrypted restic snapshots to the NAS rest server at mass-storage.mesh:8008. The plan runs at most every four hours when reachable, skips unchanged data, keeps daily/weekly/monthly buckets, and does not cross filesystem boundaries.

The table below records the final merged Nix options, not just paths mentioned in one host file. Child paths already covered by a declared parent are deduplicated before Backrest receives them.

Host Effective requested content Important exclusions or gaps
Electra /home/nimmo Model and game stores are excluded from the home-oriented plan; local Btrfs snapshots add a separate recovery layer for home
Lena /home/nimmo Claire's separate home is not selected by the composed backup plan; no local Btrfs snapshot plan
Vega Home; /srv/services; /srv/stacks; Paperless, Navidrome, SillyTavern, FreshRSS, Karakeep, BookStack, Trilium, and ytdl-sub state roots PostgreSQL dump directory and physical cluster are absent; BookStack MariaDB is absent; Engram Cloud's non-database state is absent; NAS media is outside this host plan
Lyra Home; Tdarr, Jellyfin, and Redview local state /srv/stacks, /var/lib/docker, and /srv/models are absent; NAS mounts are not traversed
Cosmos Home and /var/backups/postgresql Physical PostgreSQL cluster is intentionally not the portable backup artefact; recovery depends on successful logical dumps
Chaos Home, /var/lib/docker, and /srv/stacks Container images and mutable volume data share the Docker root, so this is broad coverage rather than a service-scoped restore set

Common excludes remove caches, dependency trees, development environments, model directories, Steam game data, and other replaceable or high-volume paths. The backup service being configured does not prove repository reachability, snapshot recency, retention success, or restore correctness; those require the backup and disaster-recovery runbooks.

Electra local snapshots

Electra alone enables the Btrbk home snapshot policy. An hourly timer snapshots /home into .btrbk-snapshots and replicates those snapshots to /run/media/snapshots on its second encrypted disk. The policy retains a short hourly set plus daily and weekly history.

These snapshots provide fast local recovery but share the same physical laptop and are not an off-host disaster-recovery copy. Backrest remains the separate off-host layer.

Declared recovery gaps and ambiguities

  • Vega's PostgreSQL logical dumps are local-only under the composed Backrest configuration.
  • BookStack's MariaDB is outside declared backup coverage.
  • Lena's home backup selects only the configured primary user's /home/nimmo; Claire's separate home is not included.
  • Engram Cloud's PostgreSQL content enters Vega's local dumps, but its local state directory is not an explicit backup path.
  • The Cosmos Paperless database remains declared while the active Paperless client points to Vega; its intended retention or retirement role needs an explicit decision.
  • NAS backup, snapshot, and replication policy is external to this repository.
  • Lyra's mutable /srv/stacks estate is not in its Backrest plan even though it remains relevant to retained Docker/SWAG services.
  • Backup declarations have not been treated as restore-test evidence.

These observations should be converted into either configuration work or explicitly accepted policy during the Security Baseline and Disaster Recovery phases. Recovery procedures belong in Operations and Runbooks, not this inventory. Return to the System Atlas or review the Service Catalogue.