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/README.md

@@ -38,5 +38,11 @@ php -S 127.0.0.1:8123 -t /tmp/uvt-demo &
 CHROME_BIN=/usr/bin/chromium python3 tools/screenshots.py
 ```
 
+## Actions-Runner (`tools/runner/`)
+
+Compose-Datei und Anleitung, um einen Forgejo-Actions-Runner einzurichten.
+Ohne Runner bleiben `ci.yml` und `release.yml` in der Warteschlange stehen.
+Details: [`tools/runner/README.md`](runner/README.md).
+
 Die Skripte sind Hilfsmittel für die Entwicklung – im Betrieb werden sie nicht
 benötigt und sind per `.htaccess` nicht über HTTP erreichbar.

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
+```

tools/runner/config.example.yml

@@ -0,0 +1,27 @@
+# Auszug aus `forgejo-runner generate-config` mit den Anpassungen, die auf
+# einem kleinen Server sinnvoll sind. Vollständige Vorlage erzeugen mit:
+#   docker compose run --rm runner forgejo-runner generate-config > data/config.yml
+
+log:
+  level: info
+
+runner:
+  file: .runner
+  # Nur ein Job gleichzeitig – der Server hat 4 GB RAM.
+  capacity: 1
+  timeout: 30m
+  # Labels bestimmen, welches Image ein `runs-on:` bekommt.
+  labels:
+    - "ubuntu-latest:docker://node:20-bookworm"
+    - "ubuntu-22.04:docker://node:20-bookworm"
+
+cache:
+  enabled: true
+  dir: "/data/cache"
+
+container:
+  network: "bridge"
+  privileged: false
+  # Images nur ziehen, wenn sie fehlen – spart Bandbreite und Platz.
+  force_pull: false
+  valid_volumes: []

tools/runner/docker-compose.yml

@@ -0,0 +1,30 @@
+# Forgejo-Actions-Runner für dieses Repository.
+#
+# Bewusst eigenständig: der Runner läuft in einem eigenen Verzeichnis und
+# fasst weder /opt/forgejo noch die dortigen Container an.
+#
+# Einrichtung siehe README.md in diesem Ordner.
+
+services:
+  runner:
+    image: data.forgejo.org/forgejo/runner:13.2.0
+    container_name: forgejo-runner
+    restart: unless-stopped
+    # Der Runner startet die Job-Container über den Docker-Socket des Hosts.
+    user: root
+    working_dir: /data
+    volumes:
+      - ./data:/data
+      - /var/run/docker.sock:/var/run/docker.sock
+    environment:
+      DOCKER_HOST: unix:///var/run/docker.sock
+      TZ: Europe/Berlin
+    command: forgejo-runner daemon --config /data/config.yml
+    # Der Server hat 4 GB – der Runner selbst soll davon wenig belegen.
+    # Die Job-Container laufen daneben, nicht innerhalb dieses Limits.
+    mem_limit: 512m
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"