fix: Move ragenix to externally managed, and ask for env file references
This commit is contained in:
213
SECRETS_QUICK_REFERENCE.md
Normal file
213
SECRETS_QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# 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 │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
Reference in New Issue
Block a user