kpr-genesis/README.md

kpr-genesis — Git‑Driven KPR Proxmox Automation
===================================================

**kpr-genesis** is both the runner and the repository that keep your Arch‑based Proxmox homelab declarative. A push to the `main` branch triggers:

1.  **Terraform** – provisions / reconciles LXCs on Proxmox.
2.  **Ansible** – installs Docker, then deploys services in those LXCs.

The first wired‑in service is the Rust paste‑bin [w4/bin](https://github.com/w4/bin).

Repository Layout
-----------------

```
kpr-genesis/
├─ scripts/
│   └─ run\_pipeline.sh        # git‑pull → terraform apply → ansible
├─ terraform/                 # infra layer (Proxmox provider)
│   ├─ main.tf
│   ├─ variables.tf
│   ├─ versions.tf
│   └─ (no outputs – DHCP IP comes from Ansible)
└─ ansible/
    ├─ inventory.proxmox.yml  # dynamic inventory (Proxmox API)
    ├─ ansible.cfg            # points to the inventory above
    ├─ requirements.yml       # galaxy roles / collections
    ├─ site.yml               # top‑level playbook
    ├─ group\_vars/
    │   └─ all.yml
    └─ roles/
        ├─ docker/
        │   └─ tasks/main.yml
        └─ bin/
            ├─ tasks/main.yml
            └─ templates/docker-compose.yml.j2
```

Prerequisites
-------------

*   Proxmox VE 8.x with an API token that has at least **PVEAdmin** on `/` (`root@pam!kpr-genesis` in the samples).
*   Arch Linux LXC named `kpr-genesis` with `terraform`, `ansible-core`, `python-proxmoxer`, and `python-requests` installed.
*   Public SSH key committed as `id_ed25519.pub` (Terraform injects it into each new container).
*   Webhook from your Gitea server hitting `http://kpr-genesis.<lan>:9000/hook`.

First‑Time Setup
----------------

\# clone the repo as the 'infra' user
```
git clone https://tetera.kernelpanic.lol/ozymandias/kpr-genesis
cd kpr-genesis
```

# install Ansible roles / collections
`ansible-galaxy install -r ansible/requirements.yml`

# export the Proxmox token
`export PROXMOX\_TOKEN=<PROXMOX TOKEN HERE>``

# run the pipeline once
```
export TF_VAR_pm_api_url=https://<PROXMOX IP HERE>:8006/api2/json
export TF_VAR_pm_user=root@pam
export TF_VAR_pm_token=<PROXMOX TOKEN HERE>
export TF_VAR_node=pacifica
export TF_VAR_bin_lxc_password='<PASSWORD HERE>'
export PROXMOX_TOKEN=<PROXMOX TOKEN HERE>

./scripts/run_pipeline.sh
```


Terraform creates a DHCP LXC named **bin**; Ansible installs Docker inside it and starts the `w4/bin` container on port 8000.

Workflow
--------

1.  Edit Terraform or Ansible files.
2.  Commit and push to `main`.
3.  Webhook triggers pipeline; infrastructure converges.

Adding a Service
----------------

1.  Add a `proxmox_lxc` block in `terraform/main.tf`.
2.  Create a role under `ansible/roles/` and reference it in `site.yml`.
3.  Commit & push — pipeline handles the rest.

Secrets
-------

Only public keys live in Git. The Proxmox token is supplied via the `PROXMOX_TOKEN` environment variable (or through Ansible Vault if preferred).

Troubleshooting
---------------

*   `ansible-inventory -i ansible/inventory.proxmox.yml --graph`
*   `journalctl -u infra-hook` for pipeline logs
*   `terraform state list` to inspect tracked resources