diff --git a/docs/operations/SECRETS_MANAGEMENT.md b/docs/operations/SECRETS_MANAGEMENT.md index 62f6e13..0394e4c 100644 --- a/docs/operations/SECRETS_MANAGEMENT.md +++ b/docs/operations/SECRETS_MANAGEMENT.md @@ -4,10 +4,10 @@ Secrets are managed in two layers: -1. **Live secrets** — `.env` files on PD at `/mnt/docker-ssd/docker/compose//.env`, gitignored and never committed to the main repo -2. **Encrypted backup** — all `.env` files are synced to a private git-crypt encrypted Gitea repo at `/mnt/docker-ssd/docker/secrets/` +1. **Live secrets** — `.env` files in the active deployment trees on PD, N.O.M.A.D., and Serenity; gitignored and never committed to the main repo +2. **Encrypted backup** — those live `.env` files are backed up into the private git-crypt encrypted Gitea repo at `/mnt/docker-ssd/docker/secrets/` on PD -The sync is a one-command operation and is safe to re-run at any time. +PD is the secrets-backup hub. PD-origin `.env` files sync locally into the encrypted repo, and standalone `.env` files from N.O.M.A.D. or Serenity must also be copied into that same encrypted repo so the backup set is not PD-only. --- @@ -37,7 +37,9 @@ openssl rand -base64 32 ## Live .env File Locations -All `.env` files live alongside their `docker-compose.yaml`: +### PD compose tree + +PD stack `.env` files live alongside their `docker-compose.yaml`: ``` /mnt/docker-ssd/docker/compose/ @@ -56,6 +58,31 @@ All `.env` files live alongside their `docker-compose.yaml`: photos/.env ``` +### N.O.M.A.D. standalone service roots + +N.O.M.A.D. keeps standalone service deployments under `/opt/`. Any service-local `.env` there is also part of the secrets backup scope. + +Backed-up examples currently include: + +``` +/opt/doris-kitchen/.env +/opt/doris-schoolhouse/.env +/opt/hawser-nomad/.env +/opt/honcho/.env +/opt/pihole-nomad/.env +/opt/technitium-nomad/.env +``` + +### Serenity appdata roots + +Serenity service-local `.env` files under `/mnt/user/appdata//.env` are also in scope for encrypted backup. + +Current verified example: + +``` +/mnt/user/appdata/technitium-serenity/.env +``` + --- ## Secrets Repo (git-crypt) @@ -72,7 +99,7 @@ All `.env` files live alongside their `docker-compose.yaml`: | Directory | Contents | |-----------|----------| -| `env/` | `.env` files for each stack, named `.env` | +| `env/` | `.env` files for PD stacks and standalone service roots, named with stable service-oriented filenames such as `.env`, `-nomad.env`, or `-serenity.env` | | `keys/` | API keys and tokens | | `certs/` | TLS certificates | | `tokens/` | Service tokens (Paperless, LiteLLM, etc.) | @@ -84,9 +111,12 @@ All files except `README.md` and `.gitattributes` are encrypted by git-crypt on ## Syncing .env Files to the Secrets Repo -Use the sync script — no root required, safe to re-run: +### PD-native compose env sync + +Use the sync script from PD after any live PD `.env` change. Run it in a root-capable context and make sure `git-crypt` is on `PATH`: ```bash +export PATH="/mnt/docker-ssd/bin:/root/bin:$PATH" bash /mnt/docker-ssd/docker/compose/scripts/sync-envs-to-secrets.sh ``` @@ -96,10 +126,35 @@ What it does: - Skips unchanged files - Commits and pushes to Gitea automatically -Run this any time you create or update a stack's `.env` file. +Run this any time you create or update a PD stack `.env` file. **Operational rule:** after any live `.env` change on PD, Doris or the operator must run the sync script and confirm whether it committed/pushed changes or reported the secrets repo already up to date. Do not treat live `.env` edits as complete until this sync step is checked. +### N.O.M.A.D. and Serenity standalone env backup rule + +Not every important `.env` lives under PD's compose tree. + +For N.O.M.A.D. `/opt//.env` files and Serenity `/mnt/user/appdata//.env` files: + +1. pull or copy the live file contents to PD through an approved host path +2. store them in `/mnt/docker-ssd/docker/secrets/env/` using a stable name like `-nomad.env` or `-serenity.env` +3. `git add`, `git commit`, and `git push` from the encrypted secrets repo on PD +4. verify the backed-up file hash matches the live source before declaring the backup complete + +Current naming examples: + +``` +env/doris-kitchen.env +env/doris-schoolhouse.env +env/hawser-nomad.env +env/honcho.env +env/pihole-nomad.env +env/technitium-nomad.env +env/technitium-serenity.env +``` + +Operationally, treat these non-PD env files as first-class backup scope. The homelab secrets backup is not complete if only PD compose env files are protected. + --- ## git-crypt on TrueNAS diff --git a/docs/servers/NOMAD.md b/docs/servers/NOMAD.md index f03489c..f29a7c5 100644 --- a/docs/servers/NOMAD.md +++ b/docs/servers/NOMAD.md @@ -201,9 +201,11 @@ These are expected to be managed by Wings/Pelican rather than a local compose fi ### Technitium Backup Resolver - Live stack path: `/opt/technitium-nomad` +- Live secrets file: `/opt/technitium-nomad/.env` - Resolver bind IP: `10.5.30.9` - Role: active DHCP-advertised backup Technitium resolver for the homelab - Config is refreshed from PD's live Technitium directory by the PD-side sync runner every 15 minutes +- The live `.env` is also backed up into the encrypted PD secrets repo as `env/technitium-nomad.env` - Same-host checks from NOMAD to `10.5.30.9` are unreliable because the resolver sits behind macvlan networking; verify from another LAN peer instead ### MeshCore to MQTT relay diff --git a/docs/servers/PLAUSIBLEDENABILITY.md b/docs/servers/PLAUSIBLEDENABILITY.md index a478d9e..8bef2a4 100644 --- a/docs/servers/PLAUSIBLEDENABILITY.md +++ b/docs/servers/PLAUSIBLEDENABILITY.md @@ -76,4 +76,3 @@ Current light-tier notes: ## Pending - Add Pangolin resource + DNS for `ai.paccoco.com` - Install fresh editor -- Set up private Gitea repo for .env file backups diff --git a/docs/servers/SERENITY.md b/docs/servers/SERENITY.md index 2ba1933..c9ef6e8 100644 --- a/docs/servers/SERENITY.md +++ b/docs/servers/SERENITY.md @@ -58,8 +58,10 @@ Managed via Unraid Community Apps. See Unraid dashboard for individual service p Serenity hosts the secondary backup Technitium node on `10.5.30.10`. - Live stack path: `/mnt/user/appdata/technitium-serenity` +- Live secrets file: `/mnt/user/appdata/technitium-serenity/.env` - Resolver bind IP: `10.5.30.10` - Config is refreshed from PD's live Technitium directory by the PD-side sync runner every 15 minutes +- The live `.env` is also backed up into the encrypted PD secrets repo as `env/technitium-serenity.env` - Same-host checks from Serenity to `10.5.30.10` are unreliable because the resolver sits behind macvlan networking; verify from another LAN peer instead ## Notes