From d8d768d8763fa7543764714328e7f2f64d4f46d0 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 24 Apr 2026 12:52:34 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20Runner-Setup-Anleitung=20f=C3=BCr=20IDF?= =?UTF-8?q?-Server?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/runner-setup.md | 149 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/runner-setup.md diff --git a/docs/runner-setup.md b/docs/runner-setup.md new file mode 100644 index 0000000..69cb47b --- /dev/null +++ b/docs/runner-setup.md @@ -0,0 +1,149 @@ +# Gitea Actions Runner — Setup + +Diese Anleitung beschreibt, wie der Gitea Actions Runner auf einem IDF-Server installiert und registriert wird. Der Runner ist der Dienst, der die Release-Workflows aus diesem Repo ausführt. Ohne laufenden Runner bleiben Tag-Pushes ohne Wirkung — die Runs hängen unendlich in der Queue. + +**Wichtig:** Diese Anleitung ist die verbindliche SSOT für das Runner-Setup. Bei jedem Server-Wechsel wird sie von vorn abgearbeitet — es gibt keine versteckten Artefakte außerhalb von Git, nur die hier beschriebenen Schritte. + +## Was der Runner ist und was er nicht ist + +Der Runner ist ein einzelnes ausführbares Binary (`act_runner`), das sich beim IDF-Gitea-Server anmeldet und Jobs aus der Queue abarbeitet. Er ist kein WordPress-, PHP- oder Plesk-Tool, sondern ein unabhängiger Dienst, der nebenher läuft. Technisch ist er vergleichbar mit einem Cron-Daemon, der auf Arbeit wartet. + +Der Runner **baut** die Plugin-ZIPs und legt sie als Gitea-Release-Assets ab. Er **verteilt** nichts an Kunden — das ist Aufgabe des Master-Key-Plugins. + +## Voraussetzungen auf dem Server + +- Linux (Debian/Ubuntu; der IDF-Plesk-Host reicht) +- Outbound-HTTPS zu `git.ihre-ideenfabrik.de` +- Standard-Tools verfügbar: `bash`, `python3`, `zip`, `unzip`, `rsync`, `curl`, `jq`, `git` + Falls einzelne Tools fehlen: `sudo apt install -y python3 zip unzip rsync curl jq git` +- systemd (Standard bei Debian/Ubuntu) +- Root-Shell-Zugang + +## Installation + +### 1. Binary herunterladen + +Aktuelle stabile Version (beim Schreiben dieser Doku: `v0.2.11`) von https://gitea.com/gitea/act_runner/releases holen: + +```bash +sudo mkdir -p /opt/act_runner +cd /opt/act_runner +sudo curl -L -o act_runner \ + https://gitea.com/gitea/act_runner/releases/download/v0.2.11/act_runner-0.2.11-linux-amd64 +sudo chmod +x act_runner +``` + +Architektur-Variante: bei ARM-Servern `linux-arm64` statt `linux-amd64` wählen. + +### 2. Konfigurationsdatei erzeugen + +```bash +sudo ./act_runner generate-config | sudo tee config.yaml > /dev/null +``` + +Die Default-Konfiguration ist ok. Relevante Stellen, falls angepasst werden muss: + +- `runner.capacity` — wie viele Jobs parallel laufen (Default: 1, für den Anfang ok) +- `runner.labels` — Labels, die der Runner kann. Hier setzen wir sie beim `register` explizit. + +### 3. Registrierungstoken in Gitea holen + +Organisation-scoped Runner (empfohlen, läuft für alle IDF-Repos): + +1. In Gitea einloggen als Admin. +2. Navigation: Organization **ideenfabrik** → Settings → **Actions** → **Runners**. +3. Button **„Create new Runner"**. +4. Registrierungstoken kopieren. + +Alternativ: Instance-weit unter Site Administration → Actions → Runners (dann verfügbar für alle Organisationen). + +### 4. Runner registrieren + +```bash +sudo ./act_runner register \ + --config /opt/act_runner/config.yaml \ + --instance https://git.ihre-ideenfabrik.de \ + --token \ + --name idf-plesk-runner \ + --labels self-hosted:host,linux:host,x64:host \ + --no-interactive +``` + +Die Labels `self-hosted`, `linux` und `x64` decken die Workflow-`runs-on:`-Kombinationen ab. Suffix `:host` = Jobs laufen direkt auf dem Host, ohne Docker. Damit sparen wir uns Docker als weitere Abhängigkeit. + +Nach erfolgreicher Registrierung liegt eine Datei `.runner` im Arbeitsverzeichnis — die ist der Runner-State, nicht weiterkopieren oder committen. + +### 5. systemd-Service anlegen + +```bash +sudo tee /etc/systemd/system/act_runner.service > /dev/null <<'EOF' +[Unit] +Description=Gitea Actions Runner (IDF) +After=network.target + +[Service] +Type=simple +WorkingDirectory=/opt/act_runner +ExecStart=/opt/act_runner/act_runner daemon --config /opt/act_runner/config.yaml +Restart=always +RestartSec=5 +User=root +Group=root + +[Install] +WantedBy=multi-user.target +EOF + +sudo systemctl daemon-reload +sudo systemctl enable act_runner +sudo systemctl start act_runner +``` + +### 6. Verifikation + +```bash +sudo systemctl status act_runner +``` + +Erwartete Zeile: `Active: active (running)`. + +In Gitea prüfen: + +1. Organization **ideenfabrik** → Settings → **Actions** → **Runners**. +2. Der neue Runner taucht mit Status **Online** auf. + +### 7. Pilot-Test + +Einen Plugin-Repo mit Caller-Workflow nehmen (z. B. `idf-post-prefix`), Tag `v` pushen, unter **Actions** im Repo prüfen, ob der Run durchläuft. Bei Erfolg entsteht ein Gitea-Release mit ZIP-Asset. + +## Laufender Betrieb + +- **Logs:** `sudo journalctl -u act_runner -f` (tail-folgen) oder `journalctl -u act_runner --since '1 hour ago'`. +- **Runner-Update:** neues `act_runner`-Binary herunterladen, ersetzen, `sudo systemctl restart act_runner`. +- **Label-Änderung:** `act_runner register` mit neuen Labels erneut ausführen (alten Runner in Gitea-UI vorher deaktivieren), Service neu starten. +- **Deregistrierung:** Runner in Gitea-UI löschen, `.runner`-Datei auf dem Server entfernen, Service stoppen. + +## Server-Wechsel — Checkliste + +Wenn der IDF-Server gewechselt wird (neuer Plesk-Host o. ä.): + +1. Diese Anleitung auf dem neuen Server von Schritt 1 an durchlaufen. +2. In Schritt 3 einen **neuen** Registrierungstoken erzeugen — alte Tokens nicht wiederverwenden. +3. Optional: den alten Runner in der Gitea-UI deaktivieren, damit er nicht doppelt zieht. +4. Nach Verifikation (Schritt 6 + 7): alte Server-Installation zurückbauen. + +Damit ist das komplette Build-System portabel: die Bauanleitung lebt in diesem Repo (`release-plugin.yml`), der Runner wird pro Server neu aufgesetzt nach genau dieser Anleitung. Keine versteckten Scripts außerhalb von Git. + +## Troubleshooting + +**Runs hängen auf `queued`, Runner steht aber auf Online.** +Label-Mismatch. Der Workflow schreibt `runs-on: self-hosted`, der Runner muss dasselbe Label haben. `act_runner register --labels …` erneut, Service neu starten. + +**Runner zeigt `offline` nach systemd-Start.** +`sudo journalctl -u act_runner --since '5 min ago'` lesen. Häufige Ursachen: Token abgelaufen, DNS funktioniert nicht, `git.ihre-ideenfabrik.de` nicht erreichbar. + +**Pre-Flight-Check im Workflow schlägt fehl mit „Tool nicht gefunden".** +Das System-Paket fehlt auf dem Host. `sudo apt install -y python3 zip unzip rsync curl jq git` nachinstallieren. + +**Release-Anlage schlägt fehl mit 401/403.** +`secrets: inherit` im Caller-Workflow prüfen und sicherstellen, dass der Runner vom Repo aus `GITEA_TOKEN` bzw. `github.token` bekommt. Alternativ Access-Token als Secret im Repo/Org setzen.