Bos55/nix-config
2
Fork 1
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity
nix-config/BOOTSTRAP.md

3.3 KiB
Raw Permalink Blame History

NixOS GitOps Bootstrap Guide

This repository is designed to be fully automated once bootstrapped, but if you are adapting this codebase for your own infrastructure, you must modify several deployment-specific variables before running the bootstrap script on a fresh Proxmox host.

Adapt the Codebase

Before bootstrapping your host, fork or clone this repository and make the following changes to match your environment:

Hardware Identifiers

  • Find your NVMe/Disk UUID: Log into your fresh Proxmox host and run: 
    ls -l /dev/disk/by-id/
    Identify your primary data disk (e.g. nvme-eui... or wwn-0x...).
  • Update OpenTofu Config: Open opentofu/nodes/mikoshi/main.tf (you may want to rename mikoshi to your host's name) and replace the disk ID inside the zpool resource with your hardware UUID.

Identity & Access

  • SSH Keys: The GitOps Control Center needs an SSH key for disaster recovery.
    • Update the Cloud-Init SSH key in opentofu/nodes/mikoshi/main.tf under the user_account block.
    • Update the permanent NixOS SSH key in nixos/users/admin/default.nix.
  • Secrets (SOPS): Replace the placeholder tokens in the Control Center host config (e.g., nixos/hosts/izanagi/secrets.yaml if you haven't renamed it) with your actual Proxmox API token and Forgejo token. Encrypt this file with your own sops Age key.

Hostname & Naming Schema

If your Proxmox host or your Control Center has a different name:

  • Rename the folders in opentofu/nodes/ and nixos/hosts/.
  • Update the node_name inside your OpenTofu main.tf.
  • Update nixos/flake.nix to reflect your new host names.

The Golden Image

Because the GitOps Control Center must be spun up fully configured without human intervention, you need a pre-built NixOS .qcow2 image.

  1. Build the golden image locally (requires Nix/WSL): 
    nix run github:nix-community/nixos-generators -- --flake ./nixos#izanagi --format qcow
  2. Upload the resulting .qcow2 file to your Proxmox node.
  3. Create a new VM in Proxmox with ID 9000.
  4. Import the .qcow2 as its disk and convert the VM into a Template. (Ensure the template has Cloud-Init configured).

Execute the Bootstrap

Once you have pushed your adapted codebase to your Git server, SSH into your fresh Proxmox node as root and run the bootstrap script:

curl -fsSL https://git.your-server.com/your-repo/raw/branch/main/scripts/bootstrap.sh | bash

What this script does automatically:

  • Fixes APT Repositories: Disables enterprise repositories and adds community repositories.
  • Fixes NIC Offloading: Installs a systemd service to safely disable TSO/GSO/GRO on physical interfaces to prevent network drops.
  • Installs OpenTofu: Pulls the official binaries.
  • Applies Host State: Runs tofu apply which:
    • Formats your specified disk into the data ZFS pool.
    • Sets laptop lid switch to ignore (if applicable).
    • Spins up the GitOps Control Center VM.

Post-Bootstrap

Once the bootstrap script completes, the Control Center VM will boot, initialize via Cloud-Init, and automatically start pulling this git repository.

From this point on, you no longer need to log into the Proxmox host. All future changes to VMs, networks, or applications should be done declaratively via Pull Requests to your repository!