Skip to main content
Deploy complete NixOS system configurations to your homelab machines using the flake’s automatic discovery system.

​
Overview

All NixOS configurations are stored in the systems/ directory. Each subdirectory with a default.nix file is automatically discovered and exposed as a nixosConfiguration.

​
Understanding Flake References

The deployment commands use flake references in the format: 
.#<hostname>
Where:
  • . refers to the current directory (your flake root)
  • # separates the flake reference from the output attribute
  • <hostname> is the name of the directory in systems/

​
Local Deployment

Deploy to the current machine you’re working on.
1

Navigate to repository

cd /path/to/homelab
2

Validate configuration

Always validate before deploying:
nix flake check
3

Deploy the system

sudo nixos-rebuild switch --flake .#<hostname>
Replace <hostname> with your system’s configuration name from systems/.
The switch command immediately activates the new configuration. Use boot instead if you want changes to apply only after reboot.

​
Deployment Commands

Different deployment modes for various scenarios: 
# Build and activate immediately
sudo nixos-rebuild switch --flake .#<hostname>

​
Remote Deployment

Deploy to a remote NixOS system over SSH.
1

Ensure SSH access

Verify you can SSH to the target system:
ssh root@<target-host>
Or configure SSH with appropriate user and sudo access.
2

Deploy remotely

nixos-rebuild switch --flake .#<hostname> --target-host root@<target-ip>
Or with a specific user:
nixos-rebuild switch --flake .#<hostname> \
  --target-host <user>@<target-ip> \
  --use-remote-sudo

​
Building from Remote Host

For systems with limited resources, build on a more powerful machine: 
nixos-rebuild switch --flake .#<hostname> \
  --target-host root@<target-ip> \
  --build-host root@<build-server-ip>

​
Dynamic Discovery

The flake automatically discovers all system configurations: 
nixosConfigurations = lib.mapAttrs mkSystem (lib.discover ./systems);
Any directory in systems/ containing default.nix is automatically available for deployment.

​
System Configuration Structure

Each system directory should contain: 
systems/<hostname>/
├── default.nix      # Main configuration
├── hardware.nix     # Hardware-specific settings (optional)
├── meta.nix         # Metadata (system architecture, etc.)
└── ...              # Additional modules

​
Rollback and Recovery

​
Rollback to Previous Generation

If a deployment causes issues: 
sudo nixos-rebuild switch --rollback

​
List Available Generations

sudo nix-env --list-generations --profile /nix/var/nix/profiles/system

​
Switch to Specific Generation

sudo /nix/var/nix/profiles/system-<number>-link/bin/switch-to-configuration switch

​
Home Manager Integration

Systems automatically include Home Manager configurations for users. The system will look for:
  • homes/<user> - Base user configuration
  • homes/<user>@<hostname> - Machine-specific overrides
These are integrated automatically and deployed with the system.

​
Troubleshooting

​
Build Failures

If the build fails:
  1. Check validation output: nix flake check
  2. Review error messages for missing options or syntax errors
  3. Verify all required inputs are accessible
  4. Check disk space: df -h /nix

​
Activation Failures

If activation fails after successful build:
  1. System remains on previous generation (safe)
  2. Check systemd journal: journalctl -xe
  3. Review activation script output
  4. Test configuration: nixos-rebuild test --flake .#<hostname>

​
SSH Deployment Issues

  • Verify SSH key authentication is configured
  • Check firewall rules on target system
  • Ensure Nix is installed on target system
  • Verify network connectivity

​
Advanced Options

​
Updating Flake Inputs

Update all dependencies before deploying: 
nix flake update
sudo nixos-rebuild switch --flake .#<hostname>

​
Update Specific Input

nix flake lock --update-input nixpkgs-weekly

​
Show Configuration Diff

See what will change: 
nixos-rebuild build --flake .#<hostname>
nvd diff /run/current-system ./result

​
Best Practices

Always run nix flake check before deploying to production systems. This validates all configurations and prevents failed deployments.
  • Test changes on non-critical systems first
  • Keep your flake inputs updated regularly
  • Document custom configurations in comments
  • Use nixos-rebuild boot for major changes
  • Maintain backup configurations
  • Version control all changes with git

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us