fix: Move ragenix to externally managed, and ask for env file references
This commit is contained in:
305
ATHENIX_INTEGRATION.md
Normal file
305
ATHENIX_INTEGRATION.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# Integrating usda-dash-config with athenix
|
||||
|
||||
This guide shows how to properly integrate the usda-vision flake and usda-dash-config module into your athenix infrastructure.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
athenix/ (main flake)
|
||||
├── flake.nix
|
||||
│ └── inputs.usda-vision (flake input)
|
||||
└── nixos-systems/
|
||||
└── inventory.nix
|
||||
└── imports usda-dash-config/default.nix (external module)
|
||||
└── receives usda-vision packages as parameter
|
||||
```
|
||||
|
||||
## Step 1: Add usda-vision as a flake input in athenix
|
||||
|
||||
In your `~/athenix/flake.nix`, add usda-vision as an input:
|
||||
|
||||
```nix
|
||||
{
|
||||
description = "Athenix infrastructure";
|
||||
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||
|
||||
# Add usda-vision flake
|
||||
usda-vision = {
|
||||
url = "path:/path/to/usda-dash-config/usda-vision";
|
||||
inputs.nixpkgs.follows = "nixpkgs";
|
||||
};
|
||||
|
||||
# Your other inputs...
|
||||
};
|
||||
|
||||
outputs = { self, nixpkgs, usda-vision, ... }: {
|
||||
# Your outputs...
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Step 2: Make packages available to NixOS modules
|
||||
|
||||
In your athenix flake outputs, ensure the usda-vision packages are available to your NixOS configurations. There are two approaches:
|
||||
|
||||
### Approach A: Using specialArgs (Recommended)
|
||||
|
||||
```nix
|
||||
outputs = { self, nixpkgs, usda-vision, ... }: {
|
||||
nixosConfigurations.usda-dash = nixpkgs.lib.nixosSystem {
|
||||
system = "x86_64-linux";
|
||||
|
||||
specialArgs = {
|
||||
# Pass usda-vision packages to all modules
|
||||
usda-vision-packages = usda-vision.packages.x86_64-linux;
|
||||
};
|
||||
|
||||
modules = [
|
||||
# Your modules...
|
||||
];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Approach B: Using _module.args
|
||||
|
||||
```nix
|
||||
outputs = { self, nixpkgs, usda-vision, ... }: {
|
||||
nixosConfigurations.usda-dash = nixpkgs.lib.nixosSystem {
|
||||
system = "x86_64-linux";
|
||||
|
||||
modules = [
|
||||
# Make packages available as module args
|
||||
{
|
||||
_module.args = {
|
||||
usda-vision-packages = usda-vision.packages.x86_64-linux;
|
||||
};
|
||||
}
|
||||
|
||||
# Your other modules...
|
||||
];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Step 3: Configure secrets with ragenix in athenix
|
||||
|
||||
Secrets are managed by ragenix in the athenix flake, not in this flake. Configure your secrets in athenix:
|
||||
|
||||
```nix
|
||||
# In your athenix flake or secrets configuration
|
||||
{
|
||||
age.secrets.usda-vision-env = {
|
||||
file = ./secrets/usda-vision/env.age; # Encrypted with ragenix in athenix
|
||||
mode = "0644";
|
||||
owner = "root";
|
||||
group = "root";
|
||||
};
|
||||
|
||||
age.secrets.usda-vision-azure-env = {
|
||||
file = ./secrets/usda-vision/azure-env.age; # Encrypted with ragenix in athenix
|
||||
mode = "0644";
|
||||
owner = "root";
|
||||
group = "root";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Step 4: Import usda-dash-config in inventory.nix
|
||||
|
||||
In your `nixos-systems/inventory.nix` (or wherever you import external modules):
|
||||
|
||||
```nix
|
||||
{ config, usda-vision-packages, ... }:
|
||||
|
||||
{
|
||||
imports = [
|
||||
# Import the usda-dash-config module, passing packages and secret paths
|
||||
(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;
|
||||
})
|
||||
|
||||
# Your other imports...
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
Or if using nix-lxc devices pattern:
|
||||
|
||||
```nix
|
||||
{ config, usda-vision-packages, ... }:
|
||||
|
||||
{
|
||||
nix-lxc = {
|
||||
devices = {
|
||||
"usda-dash" =
|
||||
let
|
||||
usda-dash-config = builtins.fetchGit {
|
||||
url = "https://git.factory.uga.edu/MODEL/usda-dash-config.git";
|
||||
rev = "commit-hash";
|
||||
submodules = true;
|
||||
};
|
||||
in
|
||||
import "${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;
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Complete Example
|
||||
|
||||
Here's a complete example of how it all fits together:
|
||||
|
||||
### ~/athenix/flake.nix
|
||||
|
||||
```nix
|
||||
{
|
||||
description = "Athenix infrastructure";
|
||||
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||
|
||||
usda-vision = {
|
||||
url = "path:/home/engr-ugaif/usda-dash-config/usda-vision";
|
||||
inputs.nixpkgs.follows = "nixpkgs";
|
||||
};
|
||||
|
||||
agenix.url = "github:ryantm/agenix";
|
||||
};
|
||||
|
||||
outputs = { self, nixpkgs, usda-vision, agenix, ... }: {
|
||||
nixosConfigurations = {
|
||||
usda-dash = nixpkgs.lib.nixosSystem {
|
||||
system = "x86_64-linux";
|
||||
|
||||
specialArgs = {
|
||||
usda-vision-packages = usda-vision.packages.x86_64-linux;
|
||||
};
|
||||
|
||||
modules = [
|
||||
agenix.nixosModules.default
|
||||
./nixos-systems/inventory.nix
|
||||
];
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### ~/athenix/nixos-systems/inventory.nix
|
||||
|
||||
```nix
|
||||
{ config, pkgs, usda-vision-packages, ... }:
|
||||
|
||||
{
|
||||
imports = [
|
||||
# Import usda-dash-config, passing the packages and secret file paths
|
||||
(import /home/engr-ugaif/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;
|
||||
})
|
||||
];
|
||||
|
||||
# Configure secrets (managed by ragenix in athenix)
|
||||
age.secrets.usda-vision-env = {
|
||||
file = ./secrets/usda-vision/env.age; # Store encrypted secrets in athenix
|
||||
mode = "0644";
|
||||
};
|
||||
|
||||
age.secrets.usda-vision-azure-env = {
|
||||
file = ./secrets/usda-vision/azure-env.age; # Azure OAuth config
|
||||
mode = "0644";
|
||||
};
|
||||
|
||||
# The usda-dash services are now configured and will use the ragenix-managed secrets
|
||||
}
|
||||
```
|
||||
|
||||
## Local Development vs Production
|
||||
|
||||
### Local Development (in usda-vision/)
|
||||
|
||||
```bash
|
||||
cd /path/to/usda-dash-config/usda-vision
|
||||
nix develop # Uses the local flake
|
||||
```
|
||||
|
||||
### Production Build (from athenix)
|
||||
|
||||
```bash
|
||||
cd ~/athenix
|
||||
nixos-rebuild switch --flake .#usda-dash
|
||||
```
|
||||
|
||||
The usda-vision packages are built by athenix and passed to the usda-dash-config module.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "usda-vision-packages is null"
|
||||
|
||||
The packages aren't being passed correctly. Check:
|
||||
- `usda-vision` is in your athenix flake inputs
|
||||
- `specialArgs` or `_module.args` includes `usda-vision-packages`
|
||||
- The import in inventory.nix uses `inherit usda-vision-packages;`
|
||||
|
||||
### "attribute 'camera-sdk' missing"
|
||||
|
||||
The usda-vision flake hasn't been built. Try:
|
||||
```bash
|
||||
nix flake update # Update the flake lock
|
||||
nix build /path/to/usda-dash-config/usda-vision#camera-sdk # Test build
|
||||
```
|
||||
|
||||
### Fallback behavior
|
||||
|
||||
If `usda-vision-packages` is not provided, the module falls back to building locally with `callPackage`. This works for standalone testing but isn't recommended for production.
|
||||
|
||||
## Benefits of This Approach
|
||||
|
||||
1. ✅ **Pure builds**: No `--impure` needed
|
||||
2. ✅ **Centralized secrets**: Secrets managed by ragenix in athenix, not in usda-vision flake
|
||||
3. ✅ **Centralized packages**: usda-vision is built once by athenix
|
||||
4. ✅ **Version control**: Lock file in athenix controls versions
|
||||
5. ✅ **Clean separation**:
|
||||
- usda-vision flake: package definitions only
|
||||
- athenix: secrets management and deployment
|
||||
- usda-dash-config: NixOS module configuration
|
||||
6. ✅ **Flexible secrets**: Can easily pass different secret files per environment (dev/staging/prod)
|
||||
|
||||
## Managing Secrets in Athenix
|
||||
|
||||
To create and manage secrets in athenix:
|
||||
|
||||
```bash
|
||||
# In athenix directory
|
||||
cd ~/athenix
|
||||
|
||||
# Create the secrets directory
|
||||
mkdir -p secrets/usda-vision
|
||||
|
||||
# Create/edit the main environment file secret
|
||||
ragenix -e secrets/usda-vision/env.age
|
||||
|
||||
# Create/edit the Azure environment file secret
|
||||
ragenix -e secrets/usda-vision/azure-env.age
|
||||
```
|
||||
|
||||
The content of `env.age` should match the format of `.env.example`:
|
||||
```bash
|
||||
VITE_SUPABASE_URL=http://127.0.0.1:54321
|
||||
VITE_SUPABASE_ANON_KEY=your-key-here
|
||||
# ... etc
|
||||
```
|
||||
- usda-vision = flake (build system)
|
||||
- usda-dash-config = module (configuration)
|
||||
- athenix = orchestrator (infrastructure)
|
||||
5. ✅ **Reusable**: Other athenix machines can use the same packages
|
||||
Reference in New Issue
Block a user