113 lines
4.5 KiB
Markdown
113 lines
4.5 KiB
Markdown
# Bootstrap Guide
|
|
|
|
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, separating between Production and Staging.
|
|
|
|
**Prerequisites:** Install `age` ([age documentation](https://github.com/FiloSottile/age)).
|
|
|
|
1. **Generate the Production Master Key**
|
|
|
|
```bash
|
|
age-keygen -o prod-master.age
|
|
```
|
|
|
|
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**
|
|
|
|
Replace both placeholders in `.sops.yaml` with the newly generated **public keys**. Commit and push this change.
|
|
|
|
## Proxmox Host Initialization & Authentication
|
|
|
|
The CI/CD pipeline needs restricted API access to Proxmox to provision Virtual Machines. We use OpenTofu to provision the bare-metal host.
|
|
|
|
### 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:
|
|
|
|
```bash
|
|
ls -l /dev/disk/by-id/
|
|
```
|
|
|
|
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
|
|
|
|
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:
|
|
|
|
```bash
|
|
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 OpenTofu 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:
|
|
|
|
```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.
|