homelab/nixos/secrets/README.md

🔐 Secrets Management (with SOPS + Nix)

This directory contains encrypted secrets used across the infrastructure managed by NixOS and sops-nix. Secrets are stored using SOPS and encrypted with an age key located on each host at /etc/sops/age.key.

---

📁 Directory Structure

secrets/
├── 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)

---

🛠 SOPS Basics

✅ Encrypt a new secret file

sops --age <YOUR-AGE-PUBKEY> secrets/myservice/secrets.yml

Example:

sops --age $(cat ~/.config/sops/age/keys.txt | grep public) -e > secrets/forgejo/secrets.yml

Press i to enter edit mode if prompted, or fill it using YAML format:

admin-password: hunter2
db-password: supersecret

---

✏️ Edit secrets in an existing file

sops secrets/forgejo/secrets.yml

---

🧬 Using Secrets in Nix

🧩 Option 1: Reference shared secrets (via defaultSopsFile)

# shared-sops.nix
{
  sops = {
    age.keyFile = "/etc/sops/age.key";
    defaultSopsFile = ../secrets/shared/secrets.yaml;

    secrets = {
      "monitoring-token".owner = "prometheus";
    };
  };
}

Then in services:

environment.etc."monitoring/token".source = config.sops.secrets."monitoring-token".path;

---

🧩 Option 2: Reference per-service secrets with explicit sopsFile

# forgejo/sops.nix
{
  sops.secrets = {
    "admin-password" = {
      sopsFile = ./../secrets/forgejo/secrets.yaml;
      owner = "forgejo";
    };
  };
}

---

🧪 Testing secrets setup

Check which secrets will be applied:

nixos-rebuild dry-activate --flake .#my-hostname

---

📚 Resources

• sops-nix
• Mozilla SOPS
• age encryption