| name | nixos-ops |
| version | 1 |
| description | NixOS Operations: Multi-Host Architecture, Deployment & Tooling |
NixOS Operations: Architecture, Deployment & Tooling
Operator's Manual for this NixOS Infrastructure
This skill covers the operational aspects of managing this multi-host NixOS repository: architecture, deployment
workflows, testing strategies, and tooling integration.
🏗️ Project Architecture
Flake Structure (flake.nix)
This repository uses a unified multi-host flake architecture.
- Inputs: Defined in
flake.nix (nixpkgs, home-manager, stylix, agenix, etc.).
- Outputs: Generates
nixosConfigurations for all hosts.
makeNixosSystem: A helper function in flake.nix that standardizes host creation:
- Injects
specialArgs: host, username, sharedVariables, hardwareProfiles.
- Sets up Overlays: Custom packages and fixes.
- Configures Home Manager: Integrated directly into the NixOS system.
Host Directory Structure
Hosts are defined in hosts/<hostname>/:
hosts/
├── common/ # Shared configurations
│ ├── hardware-profiles/ # GPU/CPU specific configs
│ └── shared-variables.nix
├── p620/ # Host: Primary Workstation
│ ├── configuration.nix # Entry point
│ ├── hardware-configuration.nix
│ └── variables.nix # Host-specific variables
├── razer/ # Host: Laptop
└── templates/ # Templates for new hosts
Module System
Modules are organized by function in modules/:
core/: System foundations (boot, locale, nix settings).
desktop/: UI environments (GNOME, Hyprland, Cosmic).
services/: System services (docker, nginx, tailscale).
features/: High-level capability flags (e.g., features.gaming.enable).
🚀 Deployment Workflows
Primary Tool: just
This project relies heavily on Justfile to abstract complex commands.
Local Deployment (Current Machine)
just deploy
just update
Remote Deployment
Specific targets are defined for each host to handle remote flags (--target-host, --build-host):
just p620
just razer
just p510
just samsung
Update Workflow
To update flake.lock (nixpkgs versions) and deploy:
just update-flake
just update-workflow <host>
Emergency Recovery
If tests fail but deployment is critical:
just emergency-deploy <host>
🧪 Testing & Validation
Always validate before deploying to production hosts.
Pre-Deployment Checks
just check-syntax
just check
just test-host <host>
Comprehensive Testing
just validate
just test-all-parallel
📦 Package Management
Custom Packages
Packages are managed via Overlays defined in flake.nix and pkgs/.
- Add new package: Create
pkgs/<package-name>/default.nix.
- Register: Add to
overlays list in flake.nix.
- Test:
just test-package <package-name>.
Finding Packages
nix search nixpkgs <query>
nix search . <query>
🛠️ Tooling Reference
nh (Nix Helper)
Used for local operations. Faster than nixos-rebuild.
nh os switch: Apply config.
nh os test: Test config.
nixos-rebuild
Used for remote operations.
nixos-rebuild switch --flake .#<host> --target-host <host>
agenix (Secrets)
See agenix skill.
just secrets: Interactive secret manager.
just test-secrets: Verify decryption.
📝 Best Practices for this Repo
- Use
just: Avoid running raw nixos-rebuild commands; use the recipes.
- Test First: Run
just test-host <target> before just <target>.
- Variables: Use
variables.nix in host directories for simple toggles instead of hardcoding.
- Hardware Profiles: Import from
hosts/common/hardware-profiles instead of copy-pasting GPU config.
- Clean Up: Run
just gc periodically to manage disk space.