# Quick Reference: Secrets Management in Athenix

## For Infrastructure Maintainers (Athenix)

### Initial Setup

```bash
# 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:**
```bash
# 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

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

**Content template for azure-env.age:**
```bash
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`):

```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

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

## For Application Developers (usda-vision)

### Local Development

```bash
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:

```bash
# 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:**
```bash
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:

```nix
# 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                 │
└─────────────────────────────────────────────────┘
```