nix-config/BOOTSTRAP.md

NixOS GitOps Bootstrap Guide

This repository is designed to be fully automated once bootstrapped. We separate concerns into two layers:

1. Host Layer: Bare-metal hardware setup on Proxmox.
2. Workload Layer: VMs and network resources.

1. Apply the Host Layer

Before deploying VMs, you need to prepare the Proxmox host.

1. Run Proxmox Post-Install Script: Log into your fresh Proxmox node's shell and run the community proxmox-ve-helper post-install script to fix the APT repositories and remove the nag screen:

   bash -c "$(wget -qLO - https://github.com/tteck/Proxmox/raw/main/misc/post-pve-install.sh)"
   

2. Clone this repository to your laptop.
3. Run the host-layer apply script using Docker (requires Docker installed). The script will automatically configure the remaining hardware-specific requirements (like the ZFS pool, NIC offloading for stability, and the laptop lid switch):

   ./scripts/apply-host-layer.sh
   

4. OpenTofu will prompt you for variables like the target node_ip, your ssh_user, and the data_disk_id (e.g. nvme-eui...) to format as ZFS.

2. Prepare 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).

3. Deploy the Workload Layer

Once the host is prepped and the template exists, you can deploy the base workloads (like the GitOps Control Center).

1. Change to the workload-layer directory:

   cd opentofu/workload-layer/production
   

2. Initialize and apply:

   tofu init
   tofu apply
   

Post-Bootstrap

Once the tofu apply 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 manually run tofu apply. All future changes to VMs, networks, or applications should be done declaratively via Pull Requests to your repository!