Einrichtung für einen Forgejo-Actions-Runner beilegen

tools/runner/ enthält eine Compose-Datei, eine Beispiel-Konfiguration und
eine Schritt-für-Schritt-Anleitung, um den Runner auf dem Server zu
registrieren. Der Runner läuft in einem eigenen Verzeichnis und fasst
/opt/forgejo nicht an.

Abgestimmt auf die vorhandenen Workflows und den Server:
- Label-Zuordnung ubuntu-latest -> node:20-bookworm, damit runs-on in
  ci.yml und release.yml greift
- capacity 1 und Speicherlimit, weil der Server nur 4 GB hat
- Hinweis darauf, was das Reichen des Docker-Sockets bedeutet, und die
  Host-Modus-Alternative samt ihrer Grenzen (setup-php braucht Container)

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

tools/runner/README.md

@@ -0,0 +1,98 @@
+# Forgejo-Actions-Runner einrichten
+
+Ohne registrierten Runner bleiben die Workflows (`ci.yml`, `release.yml`) in der
+Warteschlange stehen – Forgejo nimmt sie an, es holt sie nur niemand ab.
+
+Die folgenden Schritte laufen **als root auf dem Server** und legen den Runner in
+einem eigenen Verzeichnis an. `/opt/forgejo` und die dortigen Container bleiben
+dabei unberührt.
+
+## 1. Verzeichnis anlegen
+
+```bash
+mkdir -p /opt/forgejo-runner/data
+cd /opt/forgejo-runner
+# docker-compose.yml und config.example.yml aus tools/runner/ hierher kopieren
+```
+
+## 2. Registrierungs-Token holen
+
+Entweder in der Weboberfläche unter
+**Repository → Einstellungen → Actions → Runner → „Runner erstellen"**,
+oder über die API (Token mit Repo-Rechten vorausgesetzt):
+
+```bash
+curl -s -X POST -H "Authorization: token $FORGEJO_TOKEN" \
+  https://git.loheide.cloud/api/v1/repos/friloo/Unifi-Voucher-Tool/actions/runners/registration-token
+```
+
+Soll der Runner für **alle** Repositories zuständig sein, stattdessen
+`…/api/v1/admin/runners/registration-token` verwenden.
+
+> Das Token ist kurzlebig und wird nur einmal beim Registrieren gebraucht.
+
+## 3. Registrieren
+
+```bash
+docker compose run --rm runner forgejo-runner register --no-interactive \
+  --instance https://git.loheide.cloud \
+  --token "<REGISTRIERUNGS-TOKEN>" \
+  --name "$(hostname)-runner" \
+  --labels 'ubuntu-latest:docker://node:20-bookworm,ubuntu-22.04:docker://node:20-bookworm'
+```
+
+Die Label-Zuordnung ist wichtig: die Workflows verwenden `runs-on: ubuntu-latest`,
+und dieses Label zeigt hier auf das Image `node:20-bookworm`. Darin sind Node
+(für `actions/checkout`), Git, curl und unzip bereits enthalten.
+
+## 4. Konfiguration erzeugen und anpassen
+
+```bash
+docker compose run --rm runner forgejo-runner generate-config > data/config.yml
+```
+
+Anschließend mindestens diese Werte setzen (Vorlage: `config.example.yml`):
+
+| Wert | Empfehlung | Grund |
+|---|---|---|
+| `runner.capacity` | `1` | der Server hat 4 GB RAM |
+| `runner.timeout` | `30m` | die Jobs hier dauern wenige Minuten |
+| `container.force_pull` | `false` | spart Bandbreite und Plattenplatz |
+| `cache.enabled` | `true` | beschleunigt `composer install` |
+
+## 5. Starten
+
+```bash
+docker compose up -d
+docker compose logs -f     # sollte "Runner registered successfully" zeigen
+```
+
+Danach erscheint der Runner unter **Repository → Einstellungen → Actions → Runner**
+als „idle", und der nächste Push auf `main` baut das Release-ZIP.
+
+## Was der Runner darf – bitte bewusst entscheiden
+
+Der Runner bekommt den **Docker-Socket des Hosts** gereicht. Damit kann jeder
+Workflow, der auf diesem Runner läuft, Container mit Root-Rechten starten – das
+entspricht faktisch Root auf dem Server. Für ein privates Repository, in dem nur
+eigene Workflows laufen, ist das üblich und vertretbar. Sobald Fremde Pull
+Requests öffnen können, sollte der Runner stattdessen auf einer separaten
+Maschine oder in einer VM laufen.
+
+Alternative ohne Docker-Socket: Runner im **Host-Modus** (`ubuntu-latest:host`).
+Dann laufen die Jobs direkt auf dem Server, ohne Container – dafür müssen Node,
+Git und PHP dort installiert sein, und die Jobs sehen das Dateisystem des Hosts.
+Für `release.yml` würde das reichen, für `ci.yml` (PHP 7.4 **und** 8.2 über
+`shivammathur/setup-php`) nicht.
+
+## Speicherbedarf im Blick behalten
+
+`node:20-bookworm` belegt rund 1 GB auf der Platte, die Job-Container brauchen
+kurzzeitig einige hundert MB RAM. Bei 4 GB Gesamtspeicher sollte neben Forgejo,
+Caddy und der Datenbank nur **ein** Job gleichzeitig laufen (`capacity: 1`).
+Aufräumen gelegentlich mit:
+
+```bash
+docker image prune -f
+docker builder prune -f
+```