💠 NixOS Flake-Based Installation Guide: Disko + Encrypted Root & Swap

This is a clean, step-by-step guide for installing NixOS on a fresh system with full-disk encryption for both root and swap using disko for automated disk partitioning. The configuration is fully reproducible using Nix flakes and Git.

---

✅ Requirements

• ➡️ If you're using Wi-Fi, complete Step 0: Connect to Wi-Fi before beginning.
• Booted into the official NixOS ISO (from USB or other media).
• Stable internet connection (needed to clone your configuration repository).
• A blank disk ready to be partitioned (⚠️ ALL DATA WILL BE DESTROYED).

---

📡 Step 0: Connect to Wi-Fi

If you're on Wi-Fi, connect before continuing:

nmtui

1. Select Activate a connection → choose your Wi-Fi network → enter your password.
2. Test your connection:

ping nixos.org

---

🌐 Step 1: Clone Your Flake Configuration

Clone your flake repository to a temporary directory:

cd /tmp
git clone https://github.com/Tr1ceracop/nixos.git
cd nixos

---

⚠️ Step 2: Review Disko Configuration

IMPORTANT: Before proceeding, verify the disk device in hosts/framework/disko.nix.

# Check available disks
lsblk

# View the disko configuration
cat hosts/framework/disko.nix

The default configuration targets /dev/nvme0n1. If your disk device is different (e.g., /dev/sda), edit hosts/framework/disko.nix and change line 5:

device = "/dev/nvme0n1";  # Change this to match your disk

The disko configuration will create:

• 512M EFI boot partition (vfat) at /boot
• 864G LUKS-encrypted root partition (ext4) at /
• Remaining space for LUKS-encrypted swap

---

🔥 Step 3: Run Disko to Partition, Encrypt & Format

⚠️ WARNING: This will DESTROY ALL DATA on the target disk!

Run the disko tool to automatically partition, encrypt, and format the disk:

nix run github:nix-community/disko -- --mode disko ./hosts/framework/disko.nix

You will be prompted to:

1. Enter a LUKS passphrase for the root partition (crypt-root)
2. Enter a LUKS passphrase for the swap partition (crypt-swap)

Note: You can use the same passphrase for both or different ones. These passphrases will be required at every boot.

After disko completes, your disk will be:

• Partitioned with GPT
• Encrypted with LUKS
• Formatted with appropriate filesystems
• Mounted at /mnt

---

⚙️ Step 4: Generate Hardware Configuration

Generate the hardware configuration file that detects your system's hardware:

nixos-generate-config --no-filesystems --root /mnt

The --no-filesystems flag prevents conflicts with disko's filesystem management.

Move the generated hardware configuration into your flake:

mv /mnt/etc/nixos/hardware-configuration.nix ./hosts/framework/

Ensure hosts/framework/default.nix includes the hardware configuration (it should already be there):

imports = [
  ./hardware-configuration.nix
  ./disko.nix
  # ... other imports
];

---

🔐 Step 5: Configure Secrets (if applicable)

If you use the nm-ovpn module or other features requiring secrets, create the secrets file:

mkdir -p secrets
cat > secrets/secrets.nix <<EOF
{
  ovpn = {
    username = "your-vpn-username";
    password = "your-vpn-password";
    filepath = /path/to/your/config.ovpn;
  };
}
EOF

Security Note: The secrets/ directory is in .gitignore and should never be committed to version control.

---

🛠️ Step 6: Install NixOS from the Flake

Install NixOS using your flake configuration:

nixos-install --flake .#framework

During installation, you'll be prompted to:

1. Set the root password
2. Wait while the system builds and installs

The installation process will:

• Build the NixOS system closure
• Install the bootloader (systemd-boot)
• Copy the system to /mnt
• Set up LUKS decryption in initrd

---

🔑 Step 7: Set User Password

Since the felix user is created declaratively, set the password manually:

nixos-enter --root /mnt -c 'passwd felix'

---

🔁 Step 8: Reboot into Your Encrypted System

reboot

At boot:

1. Enter the LUKS passphrase for crypt-root (root partition)
2. Enter the LUKS passphrase for crypt-swap (swap partition)
3. Boot into GNOME and log in as felix

---

🎉 Installation complete! You now have a reproducible, flake-based, Git-managed NixOS installation with disko-managed encrypted root and swap. 🚀

---

📦 Post-Installation: Managing Your System

After installation, you can manage your system configuration:

System Updates

# Update flake inputs (nixpkgs, home-manager, disko)
cd ~/nixos
nix flake update

# Rebuild system with updates
sudo nixos-rebuild switch --flake .#framework

Home Manager Configuration

Home Manager is integrated into NixOS (built via mkSystem), so user config is applied by the same nixos-rebuild — there is no separate home-manager switch:

# Apply system + home together
sudo nixos-rebuild switch --flake ~/nixos#framework

felix's home roles are driven by the host's my.* flags: the framework host enables the desktop apps, the server host doesn't.

Development Environments

Access pre-configured development shells:

cd ~/nixos
nix develop .#qemu           # QEMU/VM testing
nix develop .#serverdev      # Server development
nix develop .#linuxdev       # Linux kernel development
nix develop .#nostromo       # STM32 / embedded
nix develop .#secOps         # Security operations
nix develop .#windows-server # Windows server tooling

---

🔐 Optional: Bootstrap Minikube TLS Root CA

The minikube-local module provides *.minikube DNS + a self-signed root CA whose public cert is system-trusted. The private key never leaves /var/lib/mkcert-minikube/ — copy it manually into a k8s Secret for cert-manager.

Three commands, run from the flake root:

# 1. First switch — generates rootCA.pem + rootCA-key.pem in /var/lib/mkcert-minikube/
sudo nixos-rebuild switch --flake .#framework

# 2. Copy the public cert into the flake (one-time, idempotent)
nix run .#minikube-tls-bootstrap

# 3. Second switch — bakes the CA into /etc/ssl/certs/ca-bundle.crt
sudo nixos-rebuild switch --flake .#framework

Wire cert-manager (one-time, in-cluster):

sudo kubectl -n cert-manager create secret tls minikube-local-ca \
  --cert=/var/lib/mkcert-minikube/rootCA.pem \
  --key=/var/lib/mkcert-minikube/rootCA-key.pem
# then point a CA ClusterIssuer at the secret.

Subsequent rebuilds: nothing to do — the activation script never overwrites an existing CA.

---

🔳 Optional: Enroll Fingerprint Sensor (fprintd + PAM)

To enable fingerprint login support on your system:

fprintd-enroll

Follow the on-screen instructions to scan and save your fingerprint. You can now log in and authenticate via sudo using your fingerprint.

---

🛠️ Alternative: Manual Installation (Without Disko)

If you prefer manual control over partitioning or need to troubleshoot, you can install without using disko's automated partitioning:

Click to expand manual installation steps

Manual Partitioning

# Create GPT partition table
parted /dev/nvme0n1 -- mklabel gpt

# Create EFI partition (512MB)
parted /dev/nvme0n1 -- mkpart primary fat32 1MiB 513MiB
parted /dev/nvme0n1 -- set 1 esp on

# Create root partition (864GB)
parted /dev/nvme0n1 -- mkpart primary ext4 513MiB 864.5GiB

# Create swap partition (remaining space)
parted /dev/nvme0n1 -- mkpart primary linux-swap 864.5GiB 100%

Encrypt with LUKS

# Encrypt root partition
cryptsetup luksFormat /dev/nvme0n1p2
cryptsetup open /dev/nvme0n1p2 crypt-root

# Encrypt swap partition
cryptsetup luksFormat /dev/nvme0n1p3
cryptsetup open /dev/nvme0n1p3 crypt-swap

Format Filesystems

mkfs.vfat -n BOOT /dev/nvme0n1p1
mkfs.ext4 /dev/mapper/crypt-root
mkswap /dev/mapper/crypt-swap

Mount Filesystems

mount /dev/mapper/crypt-root /mnt
mkdir /mnt/boot
mount /dev/nvme0n1p1 /mnt/boot
swapon /dev/mapper/crypt-swap

Continue with Installation

After manually partitioning, follow Step 4 onwards from the main installation guide, starting with generating the hardware configuration.

Important: If you use manual partitioning, you should remove the disko module from hosts/framework/default.nix:

imports = [
  ./hardware-configuration.nix
  # ./disko.nix  # Comment this out for manual installations
  # ... other imports
];

---

📚 Additional Resources

• Disko Documentation: https://github.com/nix-community/disko
• NixOS Manual: https://nixos.org/manual/nixos/stable/
• Home Manager Manual: https://nix-community.github.io/home-manager/
• NixOS Wiki: https://nixos.wiki/

For questions or issues specific to this configuration, check the CLAUDE.md file for architectural details and development workflows.