Add Gitea act runner bootstrap tooling

docs/04-configuration/GITEA_ACT_RUNNER_SETUP.md

@@ -1,8 +1,18 @@
 # Gitea act_runner Setup
 
-**Last Updated:** 2026-02-10  
+**Last Updated:** 2026-03-27 (bootstrap script + `ubuntu-latest` labels)  
 **Gitea:** https://gitea.d-bis.org  
-**Runner host:** dev-vm (VMID 5700) at 192.168.11.59
+**Runner host:** dev-vm (VMID 5700) at 192.168.11.59 (Gitea HTTP on that host: port 3000)
+
+**Which Proxmox node?** VMID 5700 is not fixed to one server—confirm before `pct exec`:
+
+```bash
+ssh root@192.168.11.10 'pct list | grep 5700'
+ssh root@192.168.11.11 'pct list | grep 5700'
+ssh root@192.168.11.12 'pct list | grep 5700'
+```
+
+Use the node where 5700 is **running** (often r630-02 / 192.168.11.12).
 
 ---
 
@@ -18,48 +28,66 @@
 
 ## Install act_runner
 
+### Site-wide (admin API token, recommended)
+
+From the **proxmox** repo root, with **`GITEA_TOKEN`** (admin) in root `.env`:
+
 ```bash
-# From Proxmox host, run inside dev-vm:
-GITEA_RUNNER_REGISTRATION_TOKEN=<token> ssh root@192.168.11.11 "pct exec 5700 -- bash -s" < scripts/dev-vm/setup-act-runner.sh
+bash scripts/dev-vm/bootstrap-gitea-act-runner-site-wide.sh
+```
+
+This calls `GET /api/v1/admin/runners/registration-token`, registers **act_runner** on CT **5700** with label **`ubuntu-latest`** (daemon shows `ubuntu-latest:host`, which matches workflow `runs-on: ubuntu-latest`), installs **systemd**, and starts the service. To re-register (e.g. change labels), run with `RUNNER_FORCE_REREGISTER=1`.
+
+### Manual registration token
+
+```bash
+# From repo root; replace <proxmox> with the node that hosts 5700 (e.g. 192.168.11.12):
+GITEA_RUNNER_REGISTRATION_TOKEN=<token> ssh root@<proxmox> "pct exec 5700 -- bash -s" < scripts/dev-vm/setup-act-runner.sh
 ```
 
 Or SSH into dev-vm (192.168.11.59) and run manually:
 
 ```bash
-cd /opt  # or preferred dir
+cd /opt/act_runner
 GITEA_RUNNER_REGISTRATION_TOKEN=<token> bash /path/to/setup-act-runner.sh
-cd /opt/act_runner && ./act_runner daemon
+```
+
+**Instance URL for `register`:** From inside dev-vm, Gitea is usually reachable as `http://127.0.0.1:3000` (same host). The setup script defaults to `http://192.168.11.59:3000`; override if needed:
+
+```bash
+INSTANCE=http://127.0.0.1:3000 GITEA_RUNNER_REGISTRATION_TOKEN=<token> bash setup-act-runner.sh
 ```
 
 ---
 
 ## Run as systemd service
 
-Create `/etc/systemd/system/act-runner.service`:
-
-```ini
-[Unit]
-Description=Gitea act_runner
-After=network.target
-
-[Service]
-Type=simple
-User=root
-WorkingDirectory=/opt/act_runner
-ExecStart=/opt/act_runner/act_runner daemon
-Restart=on-failure
-RestartSec=10
-Environment=GITEA_ACTION_URL=http://192.168.11.59:3000
-
-[Install]
-WantedBy=multi-user.target
-```
+Prefer the install script (writes the unit, enables and starts the service):
 
 ```bash
-systemctl daemon-reload
-systemctl enable --now act-runner
+ssh root@<proxmox> "pct exec 5700 -- bash -s" < scripts/dev-vm/install-act-runner-systemd.sh
 ```
 
+Optional: if Gitea is not on localhost from the runner’s view, set `GITEA_ACTION_URL` (must match a URL the runner can reach):
+
+```bash
+ssh root@<proxmox> "pct exec 5700 -- env GITEA_ACTION_URL=http://192.168.11.59:3000 bash -s" < scripts/dev-vm/install-act-runner-systemd.sh
+```
+
+Manual unit (equivalent): `/etc/systemd/system/act-runner.service` with `Environment=GITEA_ACTION_URL=http://127.0.0.1:3000`, then `systemctl daemon-reload && systemctl enable --now act-runner`.
+
+---
+
+## Troubleshooting
+
+| Symptom | Check |
+|--------|--------|
+| Jobs queued, never start | Gitea **Admin → Actions → Runners**: at least one runner **online**. Repo **Settings → Enable Repository Actions**. |
+| “No matching runner” / label errors | Workflow `runs-on:` must match runner labels (e.g. `ubuntu-latest`). In Gitea, open the runner details and compare labels. |
+| Runner exits / register errors | Ensure `INSTANCE` URL is reachable from the container (`curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/`). Re-register with a **new** token if the old one was rotated (remove `.runner` first, then run `setup-act-runner.sh` again). |
+| Docker steps fail | Install Docker on dev-vm and ensure the `act_runner` user (or root) can run `docker`. |
+| Binary but no service | If `/opt/act_runner/act_runner` exists but there is **no** `/opt/act_runner/.runner`, registration never completed—run `setup-act-runner.sh` with a token. If `.runner` exists but no unit, run `install-act-runner-systemd.sh`. |
+
 ---
 
 ## Enable Actions per repository