fix: Move ragenix to externally managed, and ask for env file references

2026-01-30 12:59:04 -05:00
parent 60d2f30680
commit 5538d54fb4
7 changed files with 728 additions and 21 deletions
--- a/SECRETS_REFACTORING.md
+++ b/SECRETS_REFACTORING.md
@@ -0,0 +1,146 @@
+# Secrets Management Refactoring
+
+## Summary of Changes
+
+This refactoring moves secrets management from the usda-vision flake to athenix (the parent infrastructure flake), following the principle that secrets should be managed centrally at the infrastructure level, not in application flakes.
+
+## What Changed
+
+### 1. Removed ragenix from usda-vision flake
+
+**Before:** usda-vision/flake.nix included ragenix as an input and provided tools for local secret management.
+
+**After:** usda-vision/flake.nix is now purely for package definitions. Ragenix is removed from inputs.
+
+**Files modified:**
+- [usda-vision/flake.nix](usda-vision/flake.nix)
+
+### 2. Updated default.nix to accept secret file paths
+
+**Before:** The module used hardcoded paths and copied .env.example files.
+
+**After:** The module accepts `envFile` and `azureEnvFile` parameters pointing to ragenix-managed secrets from athenix.
+
+**Files modified:**
+- [default.nix](default.nix)
+
+**New parameters:**
+```nix
+{ usda-vision-packages ? null
+, envFile ? null           # NEW: Path to ragenix-managed .env
+, azureEnvFile ? null      # NEW: Path to ragenix-managed .env.azure
+, ...
+}
+```
+
+### 3. Removed hardcoded .env path transformations
+
+**Before:** package.nix used sed to rewrite env_file paths in docker-compose.yml
+
+**After:** Paths are not rewritten; secrets are copied to the working directory by the systemd service
+
+**Files modified:**
+- [usda-vision/package.nix](usda-vision/package.nix)
+
+### 4. Updated integration documentation
+
+**Files modified:**
+- [ATHENIX_INTEGRATION.md](ATHENIX_INTEGRATION.md)
+
+## How to Use in Athenix
+
+### Step 1: Create secrets in athenix
+
+```bash
+cd ~/athenix
+mkdir -p secrets/usda-vision
+
+# Edit the main environment file
+ragenix -e secrets/usda-vision/env.age
+
+# Edit the Azure OAuth configuration
+ragenix -e secrets/usda-vision/azure-env.age
+```
+
+### Step 2: Configure age secrets in athenix
+
+```nix
+# In athenix flake or NixOS configuration
+{
+  age.secrets.usda-vision-env = {
+    file = ./secrets/usda-vision/env.age;
+    mode = "0644";
+    owner = "root";
+    group = "root";
+  };
+
+  age.secrets.usda-vision-azure-env = {
+    file = ./secrets/usda-vision/azure-env.age;
+    mode = "0644";
+    owner = "root";
+    group = "root";
+  };
+}
+```
+
+### Step 3: Pass secret paths to usda-dash-config module
+
+```nix
+# In inventory.nix or wherever you import usda-dash-config
+{ config, usda-vision-packages, ... }:
+
+{
+  imports = [
+    (import /path/to/usda-dash-config/default.nix {
+      inherit usda-vision-packages;
+      envFile = config.age.secrets.usda-vision-env.path;
+      azureEnvFile = config.age.secrets.usda-vision-azure-env.path;
+    })
+  ];
+}
+```
+
+## Benefits
+
+1. **Centralized secret management**: All infrastructure secrets are managed in athenix using ragenix
+2. **No hardcoded transformations**: The derivation doesn't modify env file paths
+3. **Flexible deployment**: Different secrets can be passed for dev/staging/prod environments
+4. **Pure builds**: No need for `--impure` flag since secrets aren't built into the derivation
+5. **Security**: Secrets are encrypted at rest in athenix and only decrypted on the target system
+6. **Clean separation of concerns**:
+   - usda-vision flake: Package definitions only
+   - athenix: Infrastructure and secrets management
+   - usda-dash-config: NixOS module configuration
+
+## Migration for Existing Deployments
+
+If you have existing deployments using the old approach:
+
+1. Create the secret files in athenix as shown above
+2. Copy the content from your existing `.env` files into the ragenix-managed secrets
+3. Update your inventory.nix to pass the secret file paths
+4. Rebuild with `nixos-rebuild switch`
+5. Verify the secrets are correctly copied to `/var/lib/usda-vision/.env`
+
+## Fallback Behavior
+
+If `envFile` is not provided (e.g., for local testing), the module will:
+1. Print a warning
+2. Copy `.env.example` to `/var/lib/usda-vision/.env`
+3. Remind you to configure secrets in athenix
+
+This allows the module to work standalone for development, but production deployments should always provide proper secrets.
+
+## Local Development
+
+For local development in the usda-vision directory, you can still use:
+
+```bash
+cd usda-vision
+nix develop
+cp .env.example .env
+# Edit .env with your local configuration
+docker-compose up
+```
+
+The flake.nix still provides a development shell with all necessary tools, but ragenix should be installed from athenix if needed for secret management.