docs(secrets): add beginner walkthrough for sops-nix

New docs/secrets-management.md walks through getting secrets out of
.env and into sops-encrypted YAML, assuming zero familiarity with
sops or age. Companion to the wiring landed in the prior commit.

Sections:

- Why bother — the .env failure modes (history leaks, plaintext on
  disk) and what sops/age fixes.
- What's in the box — pointers to the existing scaffold (flake input,
  modules/secrets.nix, .sops.yaml, .gitignore guards), why it's inert
  until the first encrypted file lands.
- Step-by-step — install tools, generate the age key (with a clear
  warning about back-ups + no recovery), paste the public key into
  .sops.yaml, create the first encrypted file via `sops`, declare
  secrets in NixOS, reference via config.sops.secrets.<name>.path,
  activate.
- Common operations — edit / view / rotate / updatekeys.
- Multi-host server deployment — per-host age keys at
  /var/lib/sops-nix/key.txt, path_regex-scoped recipients in
  .sops.yaml so each host only decrypts its own secrets.
- Pitfalls — don't commit unencrypted YAML, don't lose the key,
  updatekeys ≠ rotation, sops -d outputs are sensitive, the
  pathExists gate fails-silently-on-delete trap.

Linked from README "Further reading" with a one-liner noting the
sops-nix wiring already ships with the scaffold.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Padreug 2026-05-26 08:47:19 +02:00
commit fc1d31244a
2 changed files with 319 additions and 0 deletions

View file

@ -291,6 +291,12 @@ top of the human-facing docs, not a replacement for them.
Vue/Quasar UMD traps in lnbits page templates: no self-closing
tags, CSS specificity vs Quasar's `!important` utilities, cache
busting via `?v={server_startup_time}`, dark-mode color discipline.
- [`docs/secrets-management.md`](docs/secrets-management.md) —
beginner-friendly walkthrough for getting secrets out of `.env`
and into sops-encrypted YAML files: generating an age key, adding
recipients, declaring secrets in NixOS, rotating, multi-host
server setups, and common pitfalls. The scaffold ships the sops-nix
wiring already (inert until you create your first encrypted file).
## Contributing to this scaffold