Nix-Vibe/docs/installation.md

Initial Installation

This repository uses nixos-anywhere for seamless deployment to new hardware.

Prerequisites

1. SSH Access: The target machine must be booted into a Linux environment (e.g., NixOS Installer ISO) with SSH enabled and your public key authorized.
2. Secrets Management: If the target host requires secrets, ensure its Age key is generated and added to .sops.yaml as described in the SOPS Guide.
3. Disko: Ensure the disko-config.nix for the host matches the target hardware's drive names (e.g., /dev/nvme0n1 vs /dev/sda).

Deployment Command

Run this command from the root of the repository:

nix run github:nix-community/nixos-anywhere -- --flake .#<hostname> <target-ip>

Example: nix run github:nix-community/nixos-anywhere -- --flake .#x1carbon 192.168.1.50

The process will automatically partition the drive via disko, install the system, and reboot into the new NixOS environment.

Post-Installation

After the first boot, apply the configuration locally:

sudo nixos-rebuild switch --flake /etc/nixos/#<hostname>

For ongoing management, clone this repository and use the commands in the main README.md.

---

Secrets: Using Age Keys with --extra-files

Some hosts require SOPS secrets at build time (e.g., user passwords with neededForUsers = true). The private age key must be available during nixos-rebuild, but it should never be committed to Git. Use the extra-files/ directory (in .gitignore) and the --extra-files flag to supply the key securely.

1. Create the Age Key

Generate a new age key and store it in the untracked extra-files/ tree:

mkdir -p extra-files/root/.config/sops/age
age-keygen -o extra-files/root/.config/sops/age/keys.txt

Extract the public key and add it to .sops.yaml, then re-encrypt the secrets file so this key can decrypt them:

cat extra-files/root/.config/sops/age/keys.txt | age-keygen -y
# Copy the output public key into .sops.yaml under the `age` key list
sops updatekeys secrets.yaml

2. Deploy with --extra-files

The --extra-files flag copies the local extra-files/ directory into the Nix store so the age key is available at build time:

sudo nixos-rebuild switch --flake .#<hostname> --extra-files extra-files

This makes extra-files/root/.config/sops/age/keys.txt available at /root/.config/sops/age/keys.txt during evaluation, allowing SOPS to decrypt secrets.yaml without the key ever touching the target machine's filesystem.

Note

: For nixos-anywhere initial deployments, supply the age key via --extra-files as well:

nix run github:nix-community/nixos-anywhere -- --extra-files extra-files --flake .#<hostname> <target-ip>