diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md index f1ceecb..587138c 100644 --- a/BOOTSTRAP.md +++ b/BOOTSTRAP.md @@ -1,51 +1,64 @@ # 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. +This document outlines the manual steps required to initialize the NixOS GitOps environment on a fresh Proxmox host. 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. +We use `sops-nix` to manage secrets, separating between Production and Staging. **Prerequisites:** Install `age` ([age documentation](https://github.com/FiloSottile/age)). -1. **Generate the Production Master Key:** +1. **Generate the Production Master Key** ```bash 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:** + It is recommended to generate this key on a secure offline workstation. The private key should be stored in a secure offline location, such as a USB drive or printed on paper. Avoid storing this private key on any server. + +2. **Generate the Staging Master Key** + ```bash 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. +3. **Update Configuration** -## Proxmox Hypervisor Authentication & State + Replace both placeholders in `.sops.yaml` with the newly generated **public keys**. Commit and push this change. -The CI/CD pipeline needs restricted API access to Proxmox to provision Virtual Machines. +## Proxmox Host Initialization & Authentication -### 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. +The CI/CD pipeline needs restricted API access to Proxmox to provision Virtual Machines. We use OpenTofu to provision the bare-metal host. -**Prerequisites:** Install `terraform` ([Terraform installation](https://developer.hashicorp.com/terraform/downloads)). +### Find your Raw Disk ID + +The current OpenTofu configuration assumes that your system has a 2TB disk attached to the Proxmox host. This disk will be formatted and used for VM storage. + +1. Determine the persistent hardware ID of your 2TB disk, using the following command: -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: ```bash - ./scripts/control-center-bootstrap.sh + ls -l /dev/disk/by-id/ ``` -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. + + It is recommended to use the persistent hardware ID (e.g., `wwn-0x...`, `nvme-eui...`, or `ata-...`) instead of `/dev/sdb` because the latter can change between reboots. + +2. **Action Required:** Provide this ID to the system or update the `opentofu/nodes/pve-new/main.tf` configuration with this ID. + +### Apply the OpenTofu Host State + +**Prerequisites:** Install `opentofu` ([OpenTofu installation](https://opentofu.org/docs/intro/install/)). + +1. Initialize and apply the state. You will be prompted to enter your `root@pam` Proxmox credentials. + + ```bash + # Navigate to the OpenTofu host directory + cd opentofu/host + # Initialize and apply the OpenTofu configuration + tofu init + tofu apply + ``` + +2. Upon successful completion, OpenTofu will output a secure **API Token**. Copy this token securely. ## Forgejo Secrets Configuration @@ -63,6 +76,7 @@ Instead of relying on Forgejo CI/CD to store the staging private key, we use a s 1. SSH into your Proxmox server (`pve`). 2. Create the Cloud-Init snippet file: + ```bash cat << 'EOF' > /var/lib/vz/snippets/staging-key.yaml #cloud-config @@ -75,7 +89,8 @@ Instead of relying on Forgejo CI/CD to store the staging private key, we use a s - 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! + +3. This completely removes the secret from Forgejo. When OpenTofu spins up a staging VM, it simply tells Proxmox to attach this local snippet! ## TrueNAS API Security (RBAC) @@ -83,13 +98,16 @@ To prevent the CI/CD pipeline from having `root` access to your TrueNAS server, 1. Ensure you have network access to your TrueNAS host. 2. Execute the RBAC setup script: + ```bash ./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. diff --git a/flake.lock b/nixos/flake.lock similarity index 100% rename from flake.lock rename to nixos/flake.lock diff --git a/flake.nix b/nixos/flake.nix similarity index 100% rename from flake.nix rename to nixos/flake.nix diff --git a/hosts/ACE/default.nix b/nixos/hosts/ACE/default.nix similarity index 100% rename from hosts/ACE/default.nix rename to nixos/hosts/ACE/default.nix diff --git a/hosts/Binnenpost/default.nix b/nixos/hosts/Binnenpost/default.nix similarity index 100% rename from hosts/Binnenpost/default.nix rename to nixos/hosts/Binnenpost/default.nix diff --git a/hosts/Builder/default.nix b/nixos/hosts/Builder/default.nix similarity index 100% rename from hosts/Builder/default.nix rename to nixos/hosts/Builder/default.nix diff --git a/hosts/Development/default.nix b/nixos/hosts/Development/default.nix similarity index 100% rename from hosts/Development/default.nix rename to nixos/hosts/Development/default.nix diff --git a/hosts/Gitea/default.nix b/nixos/hosts/Gitea/default.nix similarity index 100% rename from hosts/Gitea/default.nix rename to nixos/hosts/Gitea/default.nix diff --git a/hosts/Ingress/default.nix b/nixos/hosts/Ingress/default.nix similarity index 100% rename from hosts/Ingress/default.nix rename to nixos/hosts/Ingress/default.nix diff --git a/hosts/Isabel/.keep b/nixos/hosts/Isabel/.keep similarity index 100% rename from hosts/Isabel/.keep rename to nixos/hosts/Isabel/.keep diff --git a/hosts/Isabel/dashboard/config/bookmarks.yaml b/nixos/hosts/Isabel/dashboard/config/bookmarks.yaml similarity index 100% rename from hosts/Isabel/dashboard/config/bookmarks.yaml rename to nixos/hosts/Isabel/dashboard/config/bookmarks.yaml diff --git a/hosts/Isabel/dashboard/config/services.yaml b/nixos/hosts/Isabel/dashboard/config/services.yaml similarity index 100% rename from hosts/Isabel/dashboard/config/services.yaml rename to nixos/hosts/Isabel/dashboard/config/services.yaml diff --git a/hosts/Isabel/default.nix b/nixos/hosts/Isabel/default.nix similarity index 100% rename from hosts/Isabel/default.nix rename to nixos/hosts/Isabel/default.nix diff --git a/hosts/Isabel/hardware-configuration.nix b/nixos/hosts/Isabel/hardware-configuration.nix similarity index 100% rename from hosts/Isabel/hardware-configuration.nix rename to nixos/hosts/Isabel/hardware-configuration.nix diff --git a/hosts/Niko/default.nix b/nixos/hosts/Niko/default.nix similarity index 100% rename from hosts/Niko/default.nix rename to nixos/hosts/Niko/default.nix diff --git a/hosts/Niko/hardware-configuration.nix b/nixos/hosts/Niko/hardware-configuration.nix similarity index 100% rename from hosts/Niko/hardware-configuration.nix rename to nixos/hosts/Niko/hardware-configuration.nix diff --git a/hosts/Production/default.nix b/nixos/hosts/Production/default.nix similarity index 100% rename from hosts/Production/default.nix rename to nixos/hosts/Production/default.nix diff --git a/hosts/ProductionArr/default.nix b/nixos/hosts/ProductionArr/default.nix similarity index 100% rename from hosts/ProductionArr/default.nix rename to nixos/hosts/ProductionArr/default.nix diff --git a/hosts/ProductionGPU/default.nix b/nixos/hosts/ProductionGPU/default.nix similarity index 100% rename from hosts/ProductionGPU/default.nix rename to nixos/hosts/ProductionGPU/default.nix diff --git a/hosts/Template/default.nix b/nixos/hosts/Template/default.nix similarity index 100% rename from hosts/Template/default.nix rename to nixos/hosts/Template/default.nix diff --git a/hosts/Testing/default.nix b/nixos/hosts/Testing/default.nix similarity index 100% rename from hosts/Testing/default.nix rename to nixos/hosts/Testing/default.nix diff --git a/hosts/Vaultwarden/default.nix b/nixos/hosts/Vaultwarden/default.nix similarity index 100% rename from hosts/Vaultwarden/default.nix rename to nixos/hosts/Vaultwarden/default.nix diff --git a/modules/apps/arr/default.nix b/nixos/modules/apps/arr/default.nix similarity index 100% rename from modules/apps/arr/default.nix rename to nixos/modules/apps/arr/default.nix diff --git a/modules/apps/bind9/db.depeuter.dev b/nixos/modules/apps/bind9/db.depeuter.dev similarity index 100% rename from modules/apps/bind9/db.depeuter.dev rename to nixos/modules/apps/bind9/db.depeuter.dev diff --git a/modules/apps/bind9/default.nix b/nixos/modules/apps/bind9/default.nix similarity index 100% rename from modules/apps/bind9/default.nix rename to nixos/modules/apps/bind9/default.nix diff --git a/modules/apps/bind9/named.conf b/nixos/modules/apps/bind9/named.conf similarity index 100% rename from modules/apps/bind9/named.conf rename to nixos/modules/apps/bind9/named.conf diff --git a/modules/apps/bind9/named.conf.local b/nixos/modules/apps/bind9/named.conf.local similarity index 100% rename from modules/apps/bind9/named.conf.local rename to nixos/modules/apps/bind9/named.conf.local diff --git a/modules/apps/bind9/named.conf.options b/nixos/modules/apps/bind9/named.conf.options similarity index 100% rename from modules/apps/bind9/named.conf.options rename to nixos/modules/apps/bind9/named.conf.options diff --git a/modules/apps/calibre/default.nix b/nixos/modules/apps/calibre/default.nix similarity index 100% rename from modules/apps/calibre/default.nix rename to nixos/modules/apps/calibre/default.nix diff --git a/modules/apps/changedetection/default.nix b/nixos/modules/apps/changedetection/default.nix similarity index 100% rename from modules/apps/changedetection/default.nix rename to nixos/modules/apps/changedetection/default.nix diff --git a/modules/apps/default.nix b/nixos/modules/apps/default.nix similarity index 100% rename from modules/apps/default.nix rename to nixos/modules/apps/default.nix diff --git a/modules/apps/freshrss/default.nix b/nixos/modules/apps/freshrss/default.nix similarity index 100% rename from modules/apps/freshrss/default.nix rename to nixos/modules/apps/freshrss/default.nix diff --git a/modules/apps/gitea/default.nix b/nixos/modules/apps/gitea/default.nix similarity index 100% rename from modules/apps/gitea/default.nix rename to nixos/modules/apps/gitea/default.nix diff --git a/modules/apps/homepage/default.nix b/nixos/modules/apps/homepage/default.nix similarity index 100% rename from modules/apps/homepage/default.nix rename to nixos/modules/apps/homepage/default.nix diff --git a/modules/apps/jellyfin/default.nix b/nixos/modules/apps/jellyfin/default.nix similarity index 100% rename from modules/apps/jellyfin/default.nix rename to nixos/modules/apps/jellyfin/default.nix diff --git a/modules/apps/monitoring/default.nix b/nixos/modules/apps/monitoring/default.nix similarity index 100% rename from modules/apps/monitoring/default.nix rename to nixos/modules/apps/monitoring/default.nix diff --git a/modules/apps/plex/default.nix b/nixos/modules/apps/plex/default.nix similarity index 100% rename from modules/apps/plex/default.nix rename to nixos/modules/apps/plex/default.nix diff --git a/modules/apps/solidtime/default.nix b/nixos/modules/apps/solidtime/default.nix similarity index 100% rename from modules/apps/solidtime/default.nix rename to nixos/modules/apps/solidtime/default.nix diff --git a/modules/apps/speedtest/default.nix b/nixos/modules/apps/speedtest/default.nix similarity index 100% rename from modules/apps/speedtest/default.nix rename to nixos/modules/apps/speedtest/default.nix diff --git a/modules/apps/technitium-dns/default.nix b/nixos/modules/apps/technitium-dns/default.nix similarity index 100% rename from modules/apps/technitium-dns/default.nix rename to nixos/modules/apps/technitium-dns/default.nix diff --git a/modules/apps/traefik/default.nix b/nixos/modules/apps/traefik/default.nix similarity index 100% rename from modules/apps/traefik/default.nix rename to nixos/modules/apps/traefik/default.nix diff --git a/modules/apps/vaultwarden/default.nix b/nixos/modules/apps/vaultwarden/default.nix similarity index 100% rename from modules/apps/vaultwarden/default.nix rename to nixos/modules/apps/vaultwarden/default.nix diff --git a/modules/common/default.nix b/nixos/modules/common/default.nix similarity index 100% rename from modules/common/default.nix rename to nixos/modules/common/default.nix diff --git a/modules/common/docker.nix b/nixos/modules/common/docker.nix similarity index 100% rename from modules/common/docker.nix rename to nixos/modules/common/docker.nix diff --git a/modules/common/gitops.nix b/nixos/modules/common/gitops.nix similarity index 98% rename from modules/common/gitops.nix rename to nixos/modules/common/gitops.nix index b2731e0..224ef4c 100644 --- a/modules/common/gitops.nix +++ b/nixos/modules/common/gitops.nix @@ -38,7 +38,7 @@ let echo "Hashes differ or unknown. Triggering nixos-rebuild..." # Trigger the build and switch - nixos-rebuild switch --flake "git+$REMOTE_URL?ref=$BRANCH" + nixos-rebuild switch --flake "git+$REMOTE_URL?dir=nixos&ref=$BRANCH" echo "Update successful." ''; diff --git a/modules/common/monitoring.nix b/nixos/modules/common/monitoring.nix similarity index 100% rename from modules/common/monitoring.nix rename to nixos/modules/common/monitoring.nix diff --git a/modules/common/nfs.nix b/nixos/modules/common/nfs.nix similarity index 100% rename from modules/common/nfs.nix rename to nixos/modules/common/nfs.nix diff --git a/modules/common/traefik.nix b/nixos/modules/common/traefik.nix similarity index 100% rename from modules/common/traefik.nix rename to nixos/modules/common/traefik.nix diff --git a/modules/common/users.nix b/nixos/modules/common/users.nix similarity index 100% rename from modules/common/users.nix rename to nixos/modules/common/users.nix diff --git a/modules/default.nix b/nixos/modules/default.nix similarity index 100% rename from modules/default.nix rename to nixos/modules/default.nix diff --git a/modules/fileSystems/default.nix b/nixos/modules/fileSystems/default.nix similarity index 100% rename from modules/fileSystems/default.nix rename to nixos/modules/fileSystems/default.nix diff --git a/modules/fileSystems/media/default.nix b/nixos/modules/fileSystems/media/default.nix similarity index 100% rename from modules/fileSystems/media/default.nix rename to nixos/modules/fileSystems/media/default.nix diff --git a/modules/fileSystems/media/video/default.nix b/nixos/modules/fileSystems/media/video/default.nix similarity index 100% rename from modules/fileSystems/media/video/default.nix rename to nixos/modules/fileSystems/media/video/default.nix diff --git a/modules/services/actions/default.nix b/nixos/modules/services/actions/default.nix similarity index 100% rename from modules/services/actions/default.nix rename to nixos/modules/services/actions/default.nix diff --git a/modules/services/default.nix b/nixos/modules/services/default.nix similarity index 100% rename from modules/services/default.nix rename to nixos/modules/services/default.nix diff --git a/modules/services/openssh/default.nix b/nixos/modules/services/openssh/default.nix similarity index 100% rename from modules/services/openssh/default.nix rename to nixos/modules/services/openssh/default.nix diff --git a/modules/virtualisation/containers/default.nix b/nixos/modules/virtualisation/containers/default.nix similarity index 100% rename from modules/virtualisation/containers/default.nix rename to nixos/modules/virtualisation/containers/default.nix diff --git a/modules/virtualisation/default.nix b/nixos/modules/virtualisation/default.nix similarity index 100% rename from modules/virtualisation/default.nix rename to nixos/modules/virtualisation/default.nix diff --git a/modules/virtualisation/guest/default.nix b/nixos/modules/virtualisation/guest/default.nix similarity index 100% rename from modules/virtualisation/guest/default.nix rename to nixos/modules/virtualisation/guest/default.nix diff --git a/users/admin/default.nix b/nixos/users/admin/default.nix similarity index 100% rename from users/admin/default.nix rename to nixos/users/admin/default.nix diff --git a/users/apps/default.nix b/nixos/users/apps/default.nix similarity index 100% rename from users/apps/default.nix rename to nixos/users/apps/default.nix diff --git a/users/backup/default.nix b/nixos/users/backup/default.nix similarity index 100% rename from users/backup/default.nix rename to nixos/users/backup/default.nix diff --git a/users/default.nix b/nixos/users/default.nix similarity index 100% rename from users/default.nix rename to nixos/users/default.nix diff --git a/users/deploy/default.nix b/nixos/users/deploy/default.nix similarity index 100% rename from users/deploy/default.nix rename to nixos/users/deploy/default.nix diff --git a/users/media/default.nix b/nixos/users/media/default.nix similarity index 100% rename from users/media/default.nix rename to nixos/users/media/default.nix diff --git a/terraform/proxmox-bootstrap/main.tf b/opentofu/proxmox-bootstrap/main.tf similarity index 100% rename from terraform/proxmox-bootstrap/main.tf rename to opentofu/proxmox-bootstrap/main.tf diff --git a/terraform/staging-env/main.tf b/opentofu/staging-env/main.tf similarity index 100% rename from terraform/staging-env/main.tf rename to opentofu/staging-env/main.tf diff --git a/scripts/control-center-bootstrap.sh b/scripts/control-center-bootstrap.sh deleted file mode 100755 index 1c12a73..0000000 --- a/scripts/control-center-bootstrap.sh +++ /dev/null @@ -1,35 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -echo "==========================================" -echo " Bootstrapping Control Center VM " -echo "==========================================" - -# Ensure script is run with appropriate permissions (this script might run as part of Cloud-Init or manually) - -if ! command -v terraform &> /dev/null; then - echo "Terraform not found. Please ensure it is installed via Nix." - exit 1 -fi - -echo "1. Initializing proxmox-bootstrap state..." -cd terraform/proxmox-bootstrap -terraform init - -echo "2. Applying proxmox-bootstrap (Requires manual approval if not passing -auto-approve)" -echo " This will configure the restricted terraform@pve user on the Proxmox host." -# Uncomment the following line to auto-approve in a fully automated environment -# terraform apply -auto-approve -terraform apply - -echo "3. Fetching the generated API token..." -TF_TOKEN=$(terraform output -raw terraform_api_token) - -echo "==========================================" -echo " IMPORTANT: Save the following token into " -echo " Forgejo Secrets as PROXMOX_TOKEN_SECRET " -echo "==========================================" -echo "$TF_TOKEN" -echo "==========================================" - -echo "Control Center Bootstrap Complete."