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