usda-dash-config/ATHENIX_INTEGRATION.md

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)
  │   └── inputs.ragenix (for secrets)
  └── nixos-systems/
      └── inventory.nix
          └── imports default.nix (accesses inputs directly)

Step 1: Add required flake inputs in athenix

In your ~/athenix/flake.nix, add usda-vision and ragenix as inputs:

{
  description = "Athenix infrastructure";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    
    # Add usda-vision flake
    usda-vision = {
      url = "git+https://git.factory.uga.edu/MODEL/usda-vision.git";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    
    # Ragenix for secrets management
    ragenix = {
      url = "github:yaxitech/ragenix";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    
    # Your other inputs...
  };

  outputs = { self, nixpkgs, usda-vision, ragenix, ... }@inputs: {
    # Your outputs...
  };
}

Step 2: Pass inputs to NixOS modules

Make inputs available to all modules via specialArgs:

outputs = { self, nixpkgs, ... }@inputs: {
  nixosConfigurations.proxmox-usda-dash = nixpkgs.lib.nixosSystem {
    system = "x86_64-linux";
    
    # Make inputs available to all modules
    specialArgs = { inherit inputs; };
    
    modules = [
      ragenix.nixosModules.default
      ./nixos-systems/inventory.nix
    ];
  };
}

Step 3: Configure secrets with ragenix in athenix

Secrets are managed by ragenix in the athenix flake:

# In your athenix configuration (e.g., inventory.nix)
{
  age.secrets.usda-vision-env = {
    file = ./secrets/usda-vision/env.age;
    mode = "0644";
    owner = "root";
    group = "root";
  };
}

Step 4: Import usda-dash-config module

Simply import the default.nix - it will access inputs and age secrets automatically:

# In inventory.nix
{ config, inputs, ... }:

{
  imports = [
    # Just import directly - no parameters needed!
    /path/to/usda-dash-config/default.nix
  ];
  
  # Configure secrets (shown above)
  age.secrets.usda-vision-env = {
    file = ./secrets/usda-vision/env.age;
    mode = "0644";
  };
  
  # Optional: Configure hostname replacement (defaults shown)
  services.usda-vision = {
    hostname = "192.168.1.156";  # Default: 192.168.1.156
    replaceHostnames = true;  # Default: true - replaces exp-dash/localhost
  };
}

Or using fetchGit:

{ config, inputs, ... }:

let
  usda-dash-config = builtins.fetchGit {
    url = "https://git.factory.uga.edu/MODEL/usda-dash-config.git";
    rev = "commit-hash";
  };
in
{
  imports = [
    "${usda-dash-config}/default.nix"
  ];
  
  # Set a custom hostname for your deployment
  services.usda-vision.hostname = "my-custom-host.local";
}

Module Options

• services.usda-vision.hostname (string, default: "192.168.1.156") - Hostname or IP to replace exp-dash/localhost with
• services.usda-vision.replaceHostnames (bool, default: true) - Whether to perform hostname replacement in docker-compose.yml

Complete Example

Here's a complete example of how it all fits together:

~/athenix/flake.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

{ config, pkgs, inputs, ... }:

{
  imports = [
    # Simply import - it accesses inputs.usda-vision automatically
    /path/to/usda-dash-config/default.nix
  ];

  # Configure secrets (managed by ragenix in athenix)
  age.secrets.usda-vision-env = {
    file = ./secrets/usda-vision/env.age;
    mode = "0644";
  };

  age.secrets.usda-vision-azure-env = {
    file = ./secrets/usda-vision/azure-env.age;
    mode = "0644";
  };
}

Local Development vs Production

Local Development (in usda-vision/)

cd /path/to/usda-dash-config/usda-vision
nix develop  # Uses the local flake

Production Build (from athenix)

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:

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:

# 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:

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