Nix-Vibe public snapshot (squashed history)

2026-09-19 13:56:12 +01:00
commit aee8fb1e9b
119 changed files with 18895 additions and 0 deletions
@@ -0,0 +1,128 @@
+# SOPS Secrets Management Guide
+
+This guide covers how to manage encrypted secrets in Nix-Vibe using `sops-nix` with `age` encryption.
+
+## Overview
+
+- **Secrets File**: `secrets.yaml` (encrypted in Git)
+- **Configuration**: `.sops.yaml` (public keys and creation rules)
+- **Private Key**: Locally stored at `~/.config/sops/age/keys.txt` (Never commit this!)
+
+## Prerequisites
+
+The project includes `sops` in the default development environment. You can also run it temporarily:
+
+```bash
+nix shell nixpkgs#sops nixpkgs#age
+```
+
+## Adding or Updating Secrets
+
+The easiest way to add a new secret (like a password or API key) is to use the `sops --set` command from the root of the repository.
+
+### Adding a Key-Value Pair
+
+```bash
+sops --set '["<host-or-category>"]["<secret-name>"] "<value>"' secrets.yaml
+```
+
+*Example (Adding a server password):*
+```bash
+sops --set '["richmond-server"]["new-password"] "supersecret123"' secrets.yaml
+```
+
+*Example (Adding a global user password):*
+```bash
+sops --set '["users"]["petere-password"] "mypassword"' secrets.yaml
+```
+
+### Editing the Secrets File Directly
+
+To open the entire decrypted file in your editor:
+
+```bash
+sops secrets.yaml
+```
+
+## Using Secrets in Configuration
+
+### 1. NixOS System Secrets
+
+In `hosts/<hostname>/configuration.nix`:
+
+```nix
+sops.secrets."machine-name/new-secret" = {
+  owner = "root";
+  group = "root";
+  mode = "0400";
+};
+```
+
+**Note:** For user passwords, add `neededForUsers = true;` to ensure the secret is decrypted early enough for the account to be created.
+
+### 2. Home Manager Secrets
+
+Home Manager secrets are defined in the user's profile (e.g., `home-manager/users/petere.nix`):
+
+```nix
+sops.secrets."gemini-api-key" = { };
+```
+
+Access the decrypted path in your configuration:
+`config.sops.secrets."gemini-api-key".path`
+
+### 3. Rendered Templates (`sops.templates`)
+
+For config files that embed a secret (e.g. an env file consumed by a container),
+use `sops.templates` so sops-nix renders the file with correct permissions and
+re-renders it at boot/switch — no shell `preStart` needed:
+
+```nix
+sops.templates."pihole-env" = {
+  content = ''
+    FTLCONF_webserver_api_password=${config.sops.placeholder."richmond-server/pihole-password"}
+  '';
+  path = "/run/pihole-env";
+  mode = "0600";
+};
+```
+
+The `${config.sops.placeholder."<secret>"}` reference is substituted with the
+decrypted value at runtime. Live examples: `hosts/richmond-server/configuration.nix`
+(pihole + castopod env files).
+
+### Multi-line Secrets
+
+Store SSH keys and other multi-line values as YAML **block scalars** (using `|`)
+so they decrypt with real newlines. `hosts/homeserver-1/configuration.nix`
+installs the `restic-ssh-key` verbatim with `install`, so that secret must be
+multi-line (not a single line with escaped spaces).
+
+## Rotating / Adding New Machine Keys
+
+When deploying to a new machine, you must generate an age key and add its public key to `.sops.yaml`.
+
+1. **Generate the key on the target machine**:
+   ```bash
+   mkdir -p ~/.config/sops/age
+   age-keygen -o ~/.config/sops/age/keys.txt
+   ```
+
+2. **Get the public key**:
+   ```bash
+   cat ~/.config/sops/age/keys.txt | age-keygen -y
+   ```
+
+3. **Update `.sops.yaml`**:
+   Add the new public key to the `age` list.
+
+4. **Re-encrypt the secrets file**:
+   ```bash
+   sops updatekeys secrets.yaml
+   ```
+
+## Troubleshooting
+
+- **"No sops config found"**: Ensure you are in the repository root.
+- **Decryption Failure**: Ensure your private key is at `~/.config/sops/age/keys.txt` or set `export SOPS_AGE_KEY_FILE=...`.
+- **Pure Evaluation Mode**: Nix Flakes in pure mode cannot read absolute paths (like `/run/secrets/...`). Use `sops.templates` or runtime injection instead of `preStart` (see `hosts/richmond-server/configuration.nix`).