> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/soriphoono/homelab/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploying NixOS Systems

> Deploy and manage NixOS system configurations

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.

<Steps>
  <Step title="Navigate to repository">
    ```bash theme={null}
    cd /path/to/homelab
    ```
  </Step>

  <Step title="Validate configuration">
    Always validate before deploying:

    ```bash theme={null}
    nix flake check
    ```
  </Step>

  <Step title="Deploy the system">
    ```bash theme={null}
    sudo nixos-rebuild switch --flake .#<hostname>
    ```

    Replace `<hostname>` with your system's configuration name from `systems/`.
  </Step>
</Steps>

<Warning>
  The `switch` command immediately activates the new configuration. Use `boot` instead if you want changes to apply only after reboot.
</Warning>

## Deployment Commands

Different deployment modes for various scenarios:

<CodeGroup>
  ```bash switch theme={null}
  # Build and activate immediately
  sudo nixos-rebuild switch --flake .#<hostname>
  ```

  ```bash boot theme={null}
  # Build and set as boot default (activate on next reboot)
  sudo nixos-rebuild boot --flake .#<hostname>
  ```

  ```bash test theme={null}
  # Build and activate temporarily (reverts on reboot)
  sudo nixos-rebuild test --flake .#<hostname>
  ```

  ```bash build theme={null}
  # Build only, don't activate
  sudo nixos-rebuild build --flake .#<hostname>
  ```
</CodeGroup>

## Remote Deployment

Deploy to a remote NixOS system over SSH.

<Steps>
  <Step title="Ensure SSH access">
    Verify you can SSH to the target system:

    ```bash theme={null}
    ssh root@<target-host>
    ```

    Or configure SSH with appropriate user and sudo access.
  </Step>

  <Step title="Deploy remotely">
    ```bash theme={null}
    nixos-rebuild switch --flake .#<hostname> --target-host root@<target-ip>
    ```

    Or with a specific user:

    ```bash theme={null}
    nixos-rebuild switch --flake .#<hostname> \
      --target-host <user>@<target-ip> \
      --use-remote-sudo
    ```
  </Step>
</Steps>

## Building from Remote Host

For systems with limited resources, build on a more powerful machine:

```bash theme={null}
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:

```nix theme={null}
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:

```bash theme={null}
sudo nixos-rebuild switch --rollback
```

### List Available Generations

```bash theme={null}
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system
```

### Switch to Specific Generation

```bash theme={null}
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:

```bash theme={null}
nix flake update
sudo nixos-rebuild switch --flake .#<hostname>
```

### Update Specific Input

```bash theme={null}
nix flake lock --update-input nixpkgs-weekly
```

### Show Configuration Diff

See what will change:

```bash theme={null}
nixos-rebuild build --flake .#<hostname>
nvd diff /run/current-system ./result
```

## Best Practices

<Warning>
  Always run `nix flake check` before deploying to production systems. This validates all configurations and prevents failed deployments.
</Warning>

* 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

* [Deploying Home Manager](/deployment/home-manager) - User-level configurations
* [Validating Changes](/deployment/validation) - Pre-deployment validation
* [Nix-on-Droid](/deployment/nix-on-droid) - Android device deployment