From 64d20da16563d755e90d9d291121e4c38cc4e68b Mon Sep 17 00:00:00 2001
From: Claude <webmaster@ihre-ideenfabrik.de>
Date: Fri, 24 Apr 2026 13:02:38 +0000
Subject: [PATCH] =?UTF-8?q?docs(runner-setup):=20Labels=20geh=C3=B6ren=20i?=
 =?UTF-8?q?n=20config.yaml,=20nicht=20ins=20register-CLI?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/runner-setup.md | 38 ++++++++++++++++++++++++++++----------
 1 file changed, 28 insertions(+), 10 deletions(-)

diff --git a/docs/runner-setup.md b/docs/runner-setup.md
index 69cb47b..f879f62 100644
--- a/docs/runner-setup.md
+++ b/docs/runner-setup.md
@@ -35,16 +35,30 @@ sudo chmod +x act_runner
 
 Architektur-Variante: bei ARM-Servern `linux-arm64` statt `linux-amd64` wählen.
 
-### 2. Konfigurationsdatei erzeugen
+### 2. Konfigurationsdatei erzeugen und Labels eintragen
 
 ```bash
 sudo ./act_runner generate-config | sudo tee config.yaml > /dev/null
 ```
 
-Die Default-Konfiguration ist ok. Relevante Stellen, falls angepasst werden muss:
+**Wichtig:** `act_runner` akzeptiert Labels **nur aus der Config**, nicht als CLI-Flag beim Registrieren. Die Default-Labels zeigen auf Docker-Images, die wir nicht brauchen. Ersetze sie durch Host-Modus-Labels:
 
-- `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.
+```bash
+sudo nano /opt/act_runner/config.yaml
+```
+
+Im Block `runner:` den vorhandenen `labels:`-Block **vollständig ersetzen** durch:
+
+```yaml
+  labels:
+    - "self-hosted:host"
+    - "linux:host"
+    - "x64:host"
+```
+
+Suffix `:host` = Jobs laufen direkt auf dem Host, ohne Docker. Damit sparen wir uns Docker als weitere Abhängigkeit. Speichern und verlassen.
+
+Andere Default-Werte in `config.yaml` können bleiben. Bei Bedarf später anpassen: `runner.capacity` für parallele Jobs (Default 1 ist für den Anfang ok).
 
 ### 3. Registrierungstoken in Gitea holen
 
@@ -53,23 +67,22 @@ 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.
+4. Registrierungstoken kopieren. Token ist einmalig — für eine zweite Registrierung einen neuen generieren.
 
 Alternativ: Instance-weit unter Site Administration → Actions → Runners (dann verfügbar für alle Organisationen).
 
 ### 4. Runner registrieren
 
 ```bash
-sudo ./act_runner register \
+sudo /opt/act_runner/act_runner register \
   --config /opt/act_runner/config.yaml \
   --instance https://git.ihre-ideenfabrik.de \
   --token <TOKEN_AUS_SCHRITT_3> \
   --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.
+Kein `--labels`-Flag — die Labels kommen aus der Config (siehe Schritt 2). Falls versehentlich mitgegeben, erscheint die Warnung `Labels from command will be ignored, use labels defined in config file.`
 
 Nach erfolgreicher Registrierung liegt eine Datei `.runner` im Arbeitsverzeichnis — die ist der Runner-State, nicht weiterkopieren oder committen.
 
@@ -111,6 +124,7 @@ In Gitea prüfen:
 
 1. Organization **ideenfabrik** → Settings → **Actions** → **Runners**.
 2. Der neue Runner taucht mit Status **Online** auf.
+3. In der Labels-Spalte müssen `self-hosted`, `linux`, `x64` stehen. Wenn stattdessen `ubuntu-latest` o. Ä. dort stehen, wurde ohne die Labels aus Schritt 2 registriert → Schritt 2 prüfen und bei Runs-Hängen neu registrieren (siehe Troubleshooting).
 
 ### 7. Pilot-Test
 
@@ -120,7 +134,8 @@ Einen Plugin-Repo mit Caller-Workflow nehmen (z. B. `idf-post-prefix`), Tag `v<X
 
 - **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.
+- **Label-Änderung:** Labels in `config.yaml` anpassen, Service neu starten (`sudo systemctl restart act_runner`). Der Daemon sendet die aktualisierten Labels beim nächsten Handshake an Gitea.
+- **Neu-Registrierung (z. B. nach kaputtem State):** `sudo rm /opt/act_runner/.runner`, neuen Token aus Gitea holen, Schritt 4 erneut ausführen, Service neu starten.
 - **Deregistrierung:** Runner in Gitea-UI löschen, `.runner`-Datei auf dem Server entfernen, Service stoppen.
 
 ## Server-Wechsel — Checkliste
@@ -136,8 +151,11 @@ Damit ist das komplette Build-System portabel: die Bauanleitung lebt in diesem R
 
 ## Troubleshooting
 
+**Warnung `Labels from command will be ignored` beim Registrieren.**
+Du hast `--labels …` als CLI-Flag gesetzt, aber `act_runner` nimmt Labels nur aus der Config. Schritt 2 durchgehen, Labels in `config.yaml` eintragen. Dann `sudo rm /opt/act_runner/.runner`, neuen Token holen, Registrierung ohne `--labels`-Flag erneut ausführen.
+
 **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.
+Label-Mismatch. Der Workflow schreibt `runs-on: self-hosted`, der Runner muss dasselbe Label anbieten. In der Gitea-UI die Labels des Runners prüfen — stehen dort nicht `self-hosted, linux, x64`, liegt es an Schritt 2.
 
 **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.