ready for runners

nixos/secrets/README.md

@@ -1,51 +1,104 @@
+# 🔐 Secrets Management (with SOPS + Nix)
 
-🔑 2. Generate an age Keypair
+This directory contains encrypted secrets used across the infrastructure managed by NixOS and [sops-nix](https://github.com/Mic92/sops-nix). Secrets are stored using [SOPS](https://github.com/mozilla/sops) and encrypted with an `age` key located on each host at `/etc/sops/age.key`.
 
-age-keygen -o secrets/age.key
+---
 
-This will output something like:
-
-# created: 2025-06-02T22:00:00Z
-# public key: age1abcdefghijk...
-
-Copy that public key somewhere — you’ll need it for encrypting.
-
-✅ You should now have:
+## 📁 Directory Structure
 
+```
 secrets/
-├── age.key        # keep this safe and private!
+├── forgejo/
+│   └── secrets.yaml            # Forgejo-specific secrets (admin password, DB password, secret key)
+├── runner/
+│   └── secrets.yaml            # Forgejo runner secrets (tokens, etc.)
+├── shared/
+│   └── secrets.yaml            # Shared secrets used across multiple VMs (SSH keys, tokens)
+````
 
-📝 3. Create Encrypted Secrets File
+---
 
-sops --age age1abcdefghijk... secrets/secrets.yaml
+## 🛠 SOPS Basics
 
-This opens a YAML file in your $EDITOR. Add secrets like:
+### ✅ Encrypt a **new secret file**
 
-forgejo-admin-password: "my-super-secret-password"
+```bash
+sops --age <YOUR-AGE-PUBKEY> -e > secrets/myservice/secrets.yaml
+````
+Example:
+```bash
+sops --age $(cat ~/.config/sops/age/keys.txt | grep public) -e > secrets/forgejo/secrets.yaml
+```
+> Press `i` to enter edit mode if prompted, or fill it using YAML format:
+```yaml
+admin-password: hunter2
+db-password: supersecret
+```
 
-Save and close the file — it’s now encrypted using the public key.
+---
 
-✅ Now you should have:
+### ✏️ Edit secrets in an existing file
 
-secrets/
-├── age.key
-├── secrets.yaml   # encrypted file (safe to commit)
+```bash
+sops secrets/forgejo/secrets.yaml
+```
 
-You can commit secrets.yaml, but do not commit age.key unless you're OK with putting it on a VM.
+---
 
+## 🧬 Using Secrets in Nix
 
-🧪 Test Decryption Locally
+### 🧩 Option 1: Reference shared secrets (via `defaultSopsFile`)
 
-export SOPS_AGE_KEY_FILE=secrets/age.key
+```nix
+# shared-sops.nix
+{
+  sops = {
+    age.keyFile = "/etc/sops/age.key";
+    defaultSopsFile = ../secrets/shared/secrets.yaml;
 
-To test:
+    secrets = {
+      "monitoring-token".owner = "prometheus";
+    };
+  };
+}
+```
 
-sops -d secrets/secrets.yaml
+Then in services:
 
-To edit:
+```nix
+environment.etc."monitoring/token".source = config.sops.secrets."monitoring-token".path;
+```
 
-sops secrets/secrets.yaml
+---
 
+### 🧩 Option 2: Reference per-service secrets with explicit `sopsFile`
 
+```nix
+# forgejo/sops.nix
+{
+  sops.secrets = {
+    "admin-password" = {
+      sopsFile = ./../secrets/forgejo/secrets.yaml;
+      owner = "forgejo";
+    };
+  };
+}
+```
 
-[plasmagoat@forgejo:~]$ sudo chmod 400 /etc/sops/age.key && sudo chown root:root /etc/sops/age.key
+---
+
+## 🧪 Testing secrets setup
+
+Check which secrets will be applied:
+
+```bash
+nixos-rebuild dry-activate --flake .#my-hostname
+```
+
+---
+
+## 📚 Resources
+
+* [sops-nix](https://github.com/Mic92/sops-nix)
+* [Mozilla SOPS](https://github.com/mozilla/sops)
+* [age encryption](https://github.com/FiloSottile/age)