usda-dash-config/SECRETS_QUICK_REFERENCE.md

Quick Reference: Secrets Management in Athenix

For Infrastructure Maintainers (Athenix)

Initial Setup

# 1. Ensure ragenix/agenix is configured in athenix
cd ~/athenix

# 2. Create secrets directory
mkdir -p secrets/usda-vision

# 3. Create the main environment secrets file
ragenix -e secrets/usda-vision/env.age

Content template for env.age:

# Supabase Configuration
VITE_SUPABASE_URL=http://127.0.0.1:54321
VITE_SUPABASE_ANON_KEY=your-anon-key-here

# Vision API Configuration
VITE_VISION_API_URL=http://exp-dash:8000
VITE_ENABLE_VIDEO_MODULE=true
VITE_VIDEO_REMOTE_URL=http://exp-dash:3001/assets/remoteEntry.js
VITE_MEDIA_API_URL=http://exp-dash:8090

# Vision System Module
VITE_ENABLE_VISION_SYSTEM_MODULE=true
VITE_VISION_SYSTEM_REMOTE_URL=http://exp-dash:3002/assets/remoteEntry.js

# Enable scheduling module
VITE_ENABLE_SCHEDULING_MODULE=true

Optional: Azure OAuth Configuration

# Create Azure OAuth secrets file
ragenix -e secrets/usda-vision/azure-env.age

Content template for azure-env.age:

AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=your-tenant-id
AZURE_REDIRECT_URI=http://your-domain/auth/callback

Configure in NixOS

Add to your athenix configuration (e.g., nixos-systems/inventory.nix):

{ config, usda-vision-packages, ... }:

{
  # Configure ragenix secrets
  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";
  };

  # Import usda-dash-config module with secret paths
  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;
    })
  ];
}

Deploy

cd ~/athenix
nixos-rebuild switch --flake .#usda-dash

For Application Developers (usda-vision)

Local Development

cd usda-vision

# Enter development environment
nix develop

# Create local .env for development
cp .env.example .env
nano .env  # Edit with your local configuration

# Start services
docker-compose up

Important Notes

• DO NOT commit .env files to the repository
• DO NOT manage secrets in the usda-vision flake
• All production secrets should be managed in athenix using ragenix
• The .env.example files are safe to commit (they contain demo values)

Checking Deployed Secrets

On the deployed system:

# Check if secrets are properly deployed
ls -la /var/lib/usda-vision/.env*

# View the active configuration (be careful with sensitive data!)
sudo cat /var/lib/usda-vision/.env

# Check systemd service status
systemctl status usda-vision

Troubleshooting

Service fails to start with "ConditionPathExists not met"

The envFile wasn't properly passed or the ragenix secret isn't configured.

Solution:

1. Verify age.secrets.usda-vision-env is configured in athenix
2. Check that envFile parameter is passed to the module
3. Rebuild with nixos-rebuild switch

.env file is empty or has wrong content

The ragenix secret might not have the right content.

Solution:

cd ~/athenix
ragenix -e secrets/usda-vision/env.age
# Verify/update the content
nixos-rebuild switch --flake .#usda-dash

Want to use different secrets for different environments

Pass different secret files:

# For production
envFile = config.age.secrets.usda-vision-env-prod.path;

# For staging
envFile = config.age.secrets.usda-vision-env-staging.path;

# For development
envFile = config.age.secrets.usda-vision-env-dev.path;

Architecture Summary

┌─────────────────────────────────────────────────┐
│ athenix (Infrastructure)                        │
│                                                 │
│  ┌─────────────────────────────────┐           │
│  │ ragenix secret management       │           │
│  │  • env.age                      │           │
│  │  • azure-env.age                │           │
│  │                                 │           │
│  │ Decrypted at deploy time →     │           │
│  │  /run/agenix/usda-vision-env   │           │
│  └─────────────────────────────────┘           │
│                    ↓                            │
│  ┌─────────────────────────────────┐           │
│  │ NixOS Configuration             │           │
│  │  imports usda-dash-config with: │           │
│  │   • usda-vision-packages        │           │
│  │   • envFile path                │           │
│  │   • azureEnvFile path           │           │
│  └─────────────────────────────────┘           │
└─────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────┐
│ usda-dash-config (NixOS Module)                 │
│                                                 │
│  Copies secrets to:                             │
│   /var/lib/usda-vision/.env                     │
│   /var/lib/usda-vision/.env.azure               │
│                                                 │
│  Starts systemd service: usda-vision            │
└─────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────┐
│ usda-vision (Application Flake)                 │
│                                                 │
│  • Package definitions only                     │
│  • No secret management                         │
│  • Development shell with tools                 │
└─────────────────────────────────────────────────┘