nix-config/BOOTSTRAP.md

Bootstrap Guide

This document outlines the manual, real-world steps required to initialize the NixOS GitOps environment for the first time. You must perform these steps before the CI/CD pipeline or any automated staging environments can function.

Secret Management Initialization

We use sops-nix to manage secrets, adhering to a strict separation between Production and Staging. You must generate these keys locally on a secure workstation.

Prerequisites: Install age (age documentation).

1. Generate the Production Master Key:

   age-keygen -o prod-master.age
   

   Caution

   It is recommended to move prod-master.age to a secure offline USB drive and/or print it on paper.

2. Generate the Staging Master Key:

   age-keygen -o staging-master.age
   

3. Update Configuration: Open both .age files and copy their Public Keys (the strings starting with age1...). Open .sops.yaml in the root of this repository and replace the placeholders with your newly generated public keys. Commit and push this change.

Proxmox Hypervisor Authentication & State

The CI/CD pipeline needs restricted API access to Proxmox to provision Virtual Machines.

Fresh Install vs. Existing Install

Warning

This repository assumes a standard, fresh installation of Proxmox VE.

If you are NOT starting from a fresh install, be aware of these potential breaking changes:

• VM ID Conflicts: Terraform automatically assigns VM IDs. If you have existing VMs, Terraform might fail to provision or (if misconfigured) attempt to overwrite them. Check your Terraform variables to ensure the ID range (e.g., 8000+) does not conflict.
• Storage Pools: The automation assumes the default Proxmox storage pools (local for snippets/ISOs, and local-lvm or local-zfs for VM disks). If you renamed your pools, you must update the Terraform configuration.
• Network Bridges: It assumes vmbr0 is available for VM networking.

Prerequisites: Install terraform (Terraform installation).

1. Ensure you have network access to your Proxmox host (e.g., via Tailscale).
2. Execute the bootstrap script from the root of the repository:

   ./scripts/control-center-bootstrap.sh
   

3. Terraform will prompt you. You will need to provide your Proxmox root@pam credentials via environment variables or prompt.
4. Upon successful completion, the script will output a secure API Token. Copy this token securely.

Forgejo Secrets Configuration

The CI/CD actions require access to the Proxmox token and the staging secret key.

1. Navigate to your Forgejo Web UI.
2. Go to Settings > Actions > Secrets for this repository.
3. Add the following repository secrets:
   • PROXMOX_TOKEN_SECRET: Paste the token generated from Step 2.
   • RENOVATE_TOKEN: Create a Personal Access Token (PAT) for your user in Forgejo with read/write access to code and pull requests, and paste it here.

Staging Golden Key Provisioning (Proxmox Snippet)

Instead of relying on Forgejo CI/CD to store the staging private key, we use a secure hypervisor-level Cloud-Init snippet.

1. SSH into your Proxmox server (pve).
2. Create the Cloud-Init snippet file:

   cat << 'EOF' > /var/lib/vz/snippets/staging-key.yaml
   #cloud-config
   write_files:
     - path: /var/lib/sops-nix/key.txt
       permissions: '0600'
       content: |
         AGE-SECRET-KEY-1... (paste your staging-master private key here)
   runcmd:
     - echo "Staging age key injected successfully."
   EOF
   

3. This completely removes the secret from Forgejo. When Terraform spins up a staging VM, it simply tells Proxmox to attach this local snippet!

TrueNAS API Security (RBAC)

To prevent the CI/CD pipeline from having root access to your TrueNAS server, you must run the RBAC bootstrap script to create a restricted user (forgejo-ci) that can only clone datasets for staging, not destroy production data.

1. Ensure you have network access to your TrueNAS host.
2. Execute the RBAC setup script:

   ./scripts/truenas-rbac-setup.sh
   

3. Provide your TrueNAS IP and the root Admin API Token when prompted.
4. The script will automatically create the custom ci-runner-role and the forgejo-ci user.
5. Follow the terminal output instructions to log into the TrueNAS Web UI as the new user and generate the restricted API token.
6. Use this restricted token for the TRUENAS_API_KEY secret in Forgejo.

Next Steps

Once these bootstrap steps are complete, the foundational authentication is in place. The Forgejo CI actions will now have the necessary permissions to build images, provision VMs, and test staging environments autonomously and securely.