Friederich Loheide
83f4223d89
Some checks are pending
CI / PHP Lint (pull_request) Waiting to run
CI / PHP Lint-1 (pull_request) Waiting to run
CI / Unit Tests & Static Analysis (pull_request) Waiting to run
CI / PHP Lint (push) Waiting to run
CI / PHP Lint-1 (push) Waiting to run
CI / Unit Tests & Static Analysis (push) Waiting to run
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>
98 lines
3.6 KiB
Markdown
98 lines
3.6 KiB
Markdown
# 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
|
||
```
|