From 83f4223d89b0ec60e904116041456f31d61bd6d4 Mon Sep 17 00:00:00 2001 From: Friederich Loheide Date: Wed, 23 Sep 2026 15:06:19 +0000 Subject: [PATCH] =?UTF-8?q?Einrichtung=20f=C3=BCr=20einen=20Forgejo-Action?= =?UTF-8?q?s-Runner=20beilegen?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- Readme.md | 3 +- tools/README.md | 6 ++ tools/runner/README.md | 98 +++++++++++++++++++++++++++++++++ tools/runner/config.example.yml | 27 +++++++++ tools/runner/docker-compose.yml | 30 ++++++++++ 5 files changed, 163 insertions(+), 1 deletion(-) create mode 100644 tools/runner/README.md create mode 100644 tools/runner/config.example.yml create mode 100644 tools/runner/docker-compose.yml diff --git a/Readme.md b/Readme.md index 890d36d..a9725d3 100644 --- a/Readme.md +++ b/Readme.md @@ -561,7 +561,8 @@ entsteht daraus ein reguläres Release mit derselben Mechanik. > verwenden, der genau diese Pfade schützt. Voraussetzung ist ein registrierter **Forgejo-Actions-Runner**; ohne Runner -bleiben die Workflows in der Warteschlange stehen. +bleiben die Workflows in der Warteschlange stehen. Compose-Datei und Anleitung +dafür liegen in [`tools/runner/`](tools/runner/README.md). ### Mitwirken diff --git a/tools/README.md b/tools/README.md index b3ece02..f3f431f 100644 --- a/tools/README.md +++ b/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. diff --git a/tools/runner/README.md b/tools/runner/README.md new file mode 100644 index 0000000..23a4b95 --- /dev/null +++ b/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 "" \ + --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 +``` diff --git a/tools/runner/config.example.yml b/tools/runner/config.example.yml new file mode 100644 index 0000000..53cc686 --- /dev/null +++ b/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: [] diff --git a/tools/runner/docker-compose.yml b/tools/runner/docker-compose.yml new file mode 100644 index 0000000..7bcfecb --- /dev/null +++ b/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" -- 2.49.1