usda-vision/FLAKE_SETUP.md

USDA Vision - Nix Flake Setup

This directory now has a Nix flake for building and developing the USDA Vision system, with ragenix for managing secrets.

Quick Start

Development Environment

Enter the development shell with all tools:

cd usda-vision
nix develop

This gives you:

• Docker & Docker Compose
• Node.js 20 with npm/pnpm
• Python 3.11 with pip/virtualenv
• Supabase CLI
• Camera SDK (automatically in LD_LIBRARY_PATH)
• ragenix for secrets management
• All standard utilities (jq, yq, rsync, etc.)

Building

Build the package:

nix build
# Or explicitly:
nix build .#usda-vision

Build just the camera SDK:

nix build .#camera-sdk

Secrets Management with ragenix

Initial Setup

1. Generate or use an age key:

# Option 1: Generate a new age key
mkdir -p ~/.config/age
age-keygen -o ~/.config/age/keys.txt

# Option 2: Use your SSH key
ssh-to-age < ~/.ssh/id_ed25519.pub
# Copy the output to secrets/secrets.nix

2. Add your public key to secrets/secrets.nix:

{
  publicKeys = [
    "age1your_public_key_here"
    # or
    "ssh-ed25519 AAAA... user@host"
  ];
}

3. Create encrypted environment files:

nix develop  # Enter dev shell first
ragenix -e secrets/env.age

This opens your $EDITOR to edit the encrypted file. Add your environment variables:

# Web environment (Vite)
VITE_SUPABASE_URL=http://exp-dash:54321
VITE_SUPABASE_ANON_KEY=your-anon-key-here
# ... etc

For Azure OAuth:

ragenix -e secrets/env.azure.age

Using Secrets in Development

In the development shell, you can:

# Edit secrets
ragenix -e secrets/env.age

# View decrypted content (careful in shared screens!)
age -d -i ~/.config/age/keys.txt secrets/env.age

# Re-encrypt all secrets after adding a new public key
ragenix -r

Using Secrets in Production (NixOS)

The flake includes a NixOS module that handles secrets automatically:

# In your NixOS configuration
{
  inputs.usda-vision.url = "path:/path/to/usda-vision";
  
  # ... in your module:
  imports = [ inputs.usda-vision.nixosModules.default ];
  
  services.usda-vision = {
    enable = true;
    secretsFile = config.age.secrets.usda-vision-env.path;
  };
  
  # Configure ragenix/agenix to decrypt the secrets
  age.secrets.usda-vision-env = {
    file = inputs.usda-vision + "/secrets/env.age";
    mode = "0644";
    owner = "root";
  };
}

Project Structure

usda-vision/
├── flake.nix           # Flake definition with outputs
├── package.nix         # Main application build
├── camera-sdk.nix      # Camera SDK build
├── secrets.nix         # ragenix configuration
├── secrets/
│   ├── secrets.nix     # Public keys
│   ├── env.age         # Encrypted .env (safe to commit)
│   ├── env.azure.age   # Encrypted Azure config (safe to commit)
│   └── README.md       # Secrets documentation
└── ... (rest of the app)

Migration from Old Setup

Old Workflow

• Manual .env file management
• Secrets in plaintext (git-ignored)
• Build defined in parent default.nix

New Workflow

• Encrypted .age files in git
• Secrets managed with ragenix
• Self-contained flake in usda-vision/
• Development shell with all tools

Migration Steps

1. Encrypt existing .env files:

cd usda-vision
nix develop

# Setup your age key first (see above)

# Encrypt the main .env
ragenix -e secrets/env.age
# Paste contents of old .env file, save and exit

# Encrypt Azure config
ragenix -e secrets/env.azure.age  
# Paste contents of old .env.azure file, save and exit

2. Delete unencrypted files (they're git-ignored but still local):

rm .env .env.azure management-dashboard-web-app/.env

3. Commit encrypted secrets:

git add secrets/env.age secrets/env.azure.age secrets/secrets.nix
git commit -m "Add encrypted secrets with ragenix"

Benefits

Security

• ✅ Secrets encrypted at rest
• ✅ Safe to commit to git
• ✅ Key-based access control
• ✅ Audit trail (git history)

Development

• ✅ Reproducible environment
• ✅ All tools included
• ✅ No manual setup
• ✅ Version-locked dependencies

Deployment

• ✅ Declarative secrets management
• ✅ Automatic decryption on NixOS
• ✅ No manual key distribution
• ✅ Clean integration with existing infrastructure

Common Tasks

Add a new developer

1. They generate an age key or use their SSH key
2. They send you their public key
3. You add it to secrets/secrets.nix
4. Re-encrypt all secrets: ragenix -r
5. Commit and push

Rotate a secret

1. Edit the encrypted file: ragenix -e secrets/env.age
2. Update the value
3. Save and exit
4. Commit: git commit secrets/env.age -m "Rotate API key"

Build without flakes

If you need to build on a system without flakes enabled:

nix-build -E '(import (fetchTarball https://github.com/edolstra/flake-compat/archive/master.tar.gz) { src = ./.; }).defaultNix.default'

Troubleshooting

"error: getting status of '...': No such file or directory"

Make sure you're in the usda-vision directory when running nix develop or nix build.

"cannot decrypt: no valid identity"

Your age private key isn't found. Check:

• ~/.config/age/keys.txt exists
• Your public key is in secrets/secrets.nix
• You've run ragenix -r after adding your key

"experimental feature 'flakes' not enabled"

Add to ~/.config/nix/nix.conf:

experimental-features = nix-command flakes

Or run with: nix --experimental-features 'nix-command flakes' develop

Further Reading

• Nix Flakes
• ragenix
• age encryption