Homelab hardware: ThinkCenter M710q Tiny, Intel i5-7500T and 8GB RAM

Highlights

These are the Nix/NixOS configurations for my homelab servers, desktop, and M1 MacBook Air

• ❄️ Nix flakes handle upstream dependencies, tracks unstable channel of Nixpkgs
• 🏠 home-manager manages dotfiles
• 🍎 nix-darwin manages MacBook
• 🤫 sops-nix manages secrets
• 🔑 Remote initrd unlock system to decrypt drives on boot
• 🌬️ Root on tmpfs aka impermanence
• 🔒 Automatic Let's Encrypt certificate registration and renewal
• 🧩 Tailscale, Nextcloud, Jellyfin, Homebridge, Scrypted, among other nice self-hosted applications
• ⚡️ justfile contains useful aliases for many frequent and atrociously long nix commands
• 🤖 flake.lock updated daily via GitHub Action, servers are configured to automatically upgrade daily via modules/nixos/auto-update.nix
• 🧱 Modular architecture promotes readability for me and copy-and-paste-ability for you

Getting started

Important

You'll need to run this script as sudo or have sudo permissions.

Warning

This script is primarily meant for my own use. Using it to install NixOS on your own hardware will fail. At minimum, you'll need to do the following before attemping installation:

1. Create a configuration for your own device in the machines/ folder
2. Retool your own sops-nix secrets or remove them entirely if you don't use sops-nix
3. Add an entry to flake.nix referencing the configuration created in step 1

bash -c "$(curl -fsSL https://raw.githubusercontent.com/eh8/chenglab/main/install.sh)"

On macOS, this script will install nix using the Determinate Systems Nix installer and prompt you to install my configuration.

On Linux, running this script from the NixOS installation ISO will prepare your system for NixOS by partitioning drives and mounting them.

Tip

When installing NixOS onto a headless local server, place your own custom NixOS ISO file onto a USB drive with Ventoy. Ventoy can automatically load the NixOS ISO file, and you can enable connectivity by building your own custom ISO with your own personal SSH key.

Useful commands 🛠️

Install just to access the simple aliases below

Locally deploy changes

just deploy macos

just deploy MACHINE

Remote deployment

To remotely deploy MACHINE, which has an IP address of 10.0.10.2

just deploy MACHINE 10.0.10.2

Edit secrets

Make sure each machine's public key is listed as entry in .sops.yaml. To modify secrets/secrets.yaml:

just secrets-edit

Syncing sops keys for a new machine

just secrets-sync

Important caveats

Changing user passwords

To modify user password, first generate a hash

echo "password" | mkpasswd -m SHA-512 -s

Then run just edit-secrets to replace the existing decrypted hash with the one that you just generated. If you use a password manager, sure to update the new password as necessary.

Changing SSH keys

Make sure you update the public key as it appears across the repository.

Installation source

Make sure the Determinate Nix installer one-liner in install.sh is consistent with how it appears on the official website.

To-do

1. Secure boot
2. Implement binary caching
3. Wireless remote unlocking

Frequently used resources

• Search NixOS options
• Home Manager Option Search
• Darwin Configuration Options

Helpful references

• An outstanding beginner friendly introduction to NixOS and flakes
• Conditional implementation
• Error when using lib.mkIf and lib.mkMerge to set configuration based on hostname
• Handling Secrets in NixOS: An Overview
• NixOS ❄: tmpfs as root
• NixOS on Hetzner Dedicated
• Setting up Nix on macOS
• Users.users..packages vs home-manager packages
• Declaratively manage dock via nix
• Dealing with post nix-flake god complex