usda-dash-config/SECRETS_REFACTORING.md

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

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

New parameters:

{ 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

4. Updated integration documentation

Files modified:

• ATHENIX_INTEGRATION.md

How to Use in Athenix

Step 1: Create secrets in athenix

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

# 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

# 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:

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.