nixos-config

NixOS flake-based configuration for a homelab cluster (Raspberry Pi nodes running k3s), desktops, laptops, and a storage node. All hosts are declared in flake.nix and built from shared modules in settings/ and services/.

Repository structure

nixos-config/
├── hardware/              # Hardware-specific modules
│   ├── apple/             # Apple devices support
│   ├── framework/         # Framework Devices
│   ├── rpi/               # Raspberry Pi devices modules
│   ├── vms/               # VM-specific hardware
│   ├── extras/            # Optional hardware like HDD, ZFS, YubiKey, Ledger, NuPhy, Rosetta
│   ├── desktop.nix        # Desktop PC hardware (AMD Hardoware)
│   └── steamdeck.nix      # Steam Deck hardware
├── settings/              # Purpose specific NixOS configuration modules
│   ├── default.nix        # Base settings applied to all hosts
│   ├── desktop/           # Desktop environment for laptops and desktops hosts
│   ├── security/          # Security hardening modules
│   ├── storage/           # Storage-node settings (ZFS, Sanoid, filesharing, etc)
│   ├── homelab.nix        # Homelab-specific settings for all homelab hosts
│   └── laptop.nix         # Laptop power/suspend settings for all laptops
└── services/              # Service modules, generic with common config, often expanded in settings)
    ├── k3s/               # k3s Kubernetes node
    ├── garage/            # Garage S3-compatible object storage
    ├── filesharing/       # Samba and Syncthing
    ├── grafana-alloy/     # Metrics/log collection agent
    ├── wireguard/         # WireGuard VPN
    ├── zfs/               # ZFS event daemon and scrub
    └── forgejo-runner/    # Forgejo CI runner

Hosts

Hostname	Architecture	Hardware	Role
framework12	x86_64	Framework 12 (13th gen Intel)	Desktop/laptop
desktop-lorenzo	x86_64	Desktop PC	Desktop
storage-*	aarch64	Raspberry Pi 5	NAS / storage node
homelab-0db5c	aarch64	Raspberry Pi 5	k3s server (control plane)
homelab-*	aarch64	Raspberry Pi 5	k3s agent
runner-*	aarch64	Raspberry Pi 4	k3s agent + Forgejo runner
steamdeck	x86_64	Steam Deck	k3s agent

Dependencies

Enter the development shell (provides git, gnupg, curl, gnumake, age, age-plugin-yubikey, openssh, ssh-to-age, sops, and other tools):

nix develop

Secrets (SOPS)

Secrets are managed with sops-nix, encrypted with age keys backed by YubiKey. The .sops.yaml file at the repo root defines which age keys can decrypt which secret paths.

To add a new host's age key (derived from its SSH host key):

make append_sops_HOSTNAME

This scans the host's SSH key via ssh-keyscan, converts it to an age key with ssh-to-age, and appends the entry to .sops.yaml.

Baking images

This flake can generate SD card images (.img.zst) and ISOs. The Makefile provides pattern targets %.img.zst and %.iso.

# All homelab and storage SD card images at once
make homelab_sds

Remote builds

Build, activate on next boot, or live-switch a remote host over SSH. The Makefile resolves HOSTNAME.local automatically.

# Build only (does not activate)
make remote_build_HOSTNAME

# Activate on next boot
make remote_boot_HOSTNAME

# Live-switch (activate immediately)
make remote_switch_HOSTNAME

Shortcuts for all homelab nodes:

# Boot all homelab nodes
make homelab_boot

# Live-switch all homelab nodes
make homelab_switch

Using nixos-rebuild

# With no secrets (pulls the flake from a remote git repo)
sudo nixos-rebuild --flake git+https://git.elates.it/koalalorenzo/nixos-config#HOSTNAME boot

Using nixos-install

# Format disks using disko
sudo nix --experimental-features "nix-command flakes" run github:nix-community/disko/latest -- --mode destroy,format,mount disko.nix

# Install (clone the repo and decrypt secrets in /tmp/nixos-config first)
sudo nixos-install --flake .#HOSTNAME --root /mnt --impure

sudo reboot

Post-install: storage nodes

Re-create Samba users. Passwords are stored in the .sops.env file.

sudo smbpasswd -a koalalorenzo
sudo smbpasswd -a longhorn
sudo smbpasswd -a immich
sudo smbpasswd -a jellyfin