Der Arbeitsrechner baut, das NAS lädt nur

Der Runner auf dem NAS scheitert an der Docker-App des UGREEN: sie lehnt
den Einhängepunkt /var/run/docker.sock ab. Nachgewiesen durch Halbieren
der Compose-Datei — ohne diese eine Zeile wird das Projekt angelegt, mit
ihr nicht, und die Meldung nennt keinen Grund.

Übrig blieben Docker-in-Docker mit privileged oder der Weg über SSH an
der Oberfläche vorbei. Beide geben dem Runner faktisch Root auf dem NAS,
und das für eine Aufgabe, die der Arbeitsrechner ohnehin erledigen kann:
er ist für die Apps nötig, weil Xcode nirgendwo sonst läuft.

Der Workflow löst deshalb nicht mehr bei jedem Push aus. Sonst sammelt
Gitea Läufe an, die niemand abarbeitet, und die Actions-Seite füllt sich
mit Leichen. Er bleibt als workflow_dispatch stehen, der Auslöser ist mit
drei Zeilen wieder da.

Die Anleitung stellt das Bauen vom Arbeitsrechner nach vorn und hält zwei
Dinge fest, die beim Einrichten Zeit gekostet haben: die Docker-App zieht
Images nicht selbst, und die Anmeldung an der Registry will ein
Zugriffstoken statt des Kontopassworts.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.gitea/workflows/image.yml

@@ -1,20 +1,29 @@
 # Baut das Flaro-Image und legt es in die Registry dieses Gitea.
 #
-# **Warum hier und nicht auf dem Arbeitsrechner.** Ein Bau von Hand heisst:
-# jemand muss daran denken, muss die richtige Architektur angeben und muss
-# angemeldet sein. Hier passiert es bei jedem Push von selbst, immer für
-# beide Architekturen, und die Anmeldung besorgt Gitea.
+# **Zur Zeit schläft diese Datei.** Gebaut wird auf dem Arbeitsrechner mit
+# `Tools/image-veroeffentlichen.sh` — der Rechner ist für die Apps ohnehin
+# nötig, weil Xcode nirgendwo sonst läuft.
 #
-# **Voraussetzung ist ein Runner.** Ohne einen registrierten Act-Runner
-# läuft diese Datei nie an — dann bleibt der Weg von Hand aus
-# `Tools/image-veroeffentlichen.sh`.
+# **Weil Gitea nicht selbst baut.** Es verteilt Arbeit an einen Act-Runner,
+# und der müsste auf dem NAS laufen. Dort scheitert er: sein Zweck ist das
+# Bauen von Images, also braucht er Zugriff auf Docker, und die Docker-App
+# des UGREEN lehnt den Einhängepunkt `/var/run/docker.sock` ab. Übrig
+# blieben `privileged: true` oder der Weg über SSH an der Oberfläche vorbei
+# — beides gibt dem Runner faktisch Root auf dem NAS.
+#
+# **Deshalb nur `workflow_dispatch`.** Mit einem Push-Auslöser legt Gitea
+# bei jedem Push einen Lauf an, den niemand abarbeitet; nach einer Woche
+# steht die Actions-Seite voll mit Leichen. Kommt irgendwann ein Runner
+# dazu, lässt sich der Lauf von Hand starten — und der Auslöser unten ist
+# mit drei Zeilen wieder da.
 
 name: Image bauen und veröffentlichen
 
 on:
-  push:
-    branches: [main]
-    tags: ['v*']
+  # Wieder automatisch, sobald ein Runner existiert:
+  #   push:
+  #     branches: [main]
+  #     tags: ['v*']
   workflow_dispatch:
 
 jobs:

docs/NAS-EINRICHTEN.md

@@ -42,41 +42,36 @@ Ein Mac baut ohne Angabe **arm64** — also gehört die Angabe dazu.
 
 ## Schritt 2: Das Image auf das NAS bringen
 
-Drei Wege. Der erste ist der bequemste, der zweite braucht keine Registry.
+**Das NAS baut nicht, es lädt nur.** Genau wie bei Jellyfin oder jedem
+anderen Container: dort baut jemand anderes und veröffentlicht, du ziehst
+das Ergebnis. Bei Flaro ist dieser Jemand dein Arbeitsrechner — er ist für
+die Apps ohnehin nötig, weil Xcode nirgendwo sonst läuft.
+
+Drei Wege. Der erste ist der vorgesehene; der zweite braucht keine Registry.
 
 ### Weg A — über die Registry deines Gitea (empfohlen)
 
 Dein Gitea unter `git.scarriffle.com` bringt eine Container-Registry mit.
 Einmal einrichten, danach ist jedes Update ein `docker compose pull`.
 
-#### A1 · Gitea baut selbst
+#### A1 · Anmelden, einmalig
 
-`.gitea/workflows/image.yml` liegt im Projekt. Bei jedem Push auf `main`
-baut Gitea das Image für **beide** Architekturen und legt es ab — ohne dass
-jemand daran denken muss, und ohne Anmeldung am Arbeitsrechner.
-
-**Voraussetzung ist ein registrierter Act-Runner.** Gitea verteilt Arbeit
-nur, es baut nicht selbst: ohne Runner legt es bei jedem Push einen Lauf an,
-der dann liegenbleibt. Nachsehen unter
-*Repo → Einstellungen → Actions → Runner*.
-
-Der Runner gehört **auf das NAS** — dort läuft Docker ohnehin, und damit
-braucht es für ein neues Image nie wieder einen Arbeitsrechner. Fertig
-vorbereitet liegt er in `server/docker-compose.runner.yml`; hineingehört nur
-das Registrierungstoken aus derselben Gitea-Seite.
-
-Danach erscheint der Runner in der Liste, und der wartende Lauf startet —
-oder spätestens der nächste Push.
-
-#### A2 · Von Hand vom Arbeitsrechner
-
-Einmalig anmelden — das Passwort tippst du selbst ein:
+Nicht mit dem Kontopasswort, sondern mit einem Zugriffstoken: *Gitea →
+Einstellungen → Anwendungen → Zugriffstoken*, Berechtigungen
+`write:package` und `read:package`. Ein Token lässt sich einzeln widerrufen,
+und bei eingeschalteter Zwei-Faktor-Anmeldung funktioniert das Passwort hier
+gar nicht.
 
 ```bash
 docker login git.scarriffle.com
 ```
 
-Danach genügt ein Befehl; er baut amd64 **und** arm64 und lädt hoch:
+Benutzername ist dein Gitea-Name, als Passwort das Token.
+
+#### A2 · Bauen und hochladen
+
+Ein Befehl; er baut amd64 **und** arm64 und lädt beides als ein Manifest
+hoch:
 
 ```bash
 Tools/image-veroeffentlichen.sh
@@ -88,6 +83,13 @@ Mit einer Fassungsnummer, wenn du sie festnageln willst:
 Tools/image-veroeffentlichen.sh 0.2.0
 ```
 
+Nur die Architektur des NAS — deutlich schneller, weil die fremde sonst
+unter Emulation gebaut wird:
+
+```bash
+FLARO_PLATTFORMEN=linux/amd64 Tools/image-veroeffentlichen.sh
+```
+
 #### A3 · Das Paket öffentlich stellen
 
 Sonst muss sich auch das NAS anmelden. In Gitea unter
@@ -108,9 +110,15 @@ kommt:
 
 **Bestätigen** — danach findet die Suche in der Docker-App auch
 `scarriffle/flaro`. Ist das Paket privat, trägst du unter
-*Registierungseinstellungen* Benutzername und ein Gitea-Zugriffstoken ein
-(nicht dein Kontopasswort: ein Token lässt sich einzeln widerrufen, unter
-*Einstellungen → Anwendungen → Zugriffstoken*, Berechtigung `read:package`).
+*Registierungseinstellungen* Benutzername und dasselbe Zugriffstoken ein.
+
+#### A5 · Das Image herunterladen, bevor du das Projekt anlegst
+
+**Die Docker-App zieht Images nicht selbst.** Steht in einer Compose-Datei
+ein Image, das lokal fehlt, bricht sie das Anlegen mit „Bitte überprüfen Sie
+die Konfigurationsinformationen" ab — ohne zu sagen, woran es liegt. Also
+vorher **Image → Herunterladen**, Registry `gitea`, Quellname
+`scarriffle/flaro:latest`.
 
 In der Compose-Datei steht dann:
 
@@ -141,11 +149,23 @@ docker load < /volume1/docker/flaro.tar.gz
 
 In der Compose-Datei steht dann schlicht `image: flaro:latest`.
 
-### Weg C — auf dem NAS bauen
+### Weg C — Gitea baut selbst
 
-Geht, lohnt sich aber selten: der Bau braucht den Quelltext, Node, das
-.NET-SDK als Zwischenschritt und ordentlich Arbeitsspeicher. Die Docker-App
-von UGREEN kann `build:` in einer Compose-Datei ausserdem nicht immer.
+`.gitea/workflows/image.yml` liegt im Projekt und kann denselben Bau auf
+einem Act-Runner ausführen. **Gitea verteilt Arbeit nur, es baut nicht
+selbst** — ohne registrierten Runner passiert nichts.
+
+Der Runner müsste auf dem NAS laufen, und daran scheitert es dort: er
+braucht Zugriff auf Docker, denn sein Zweck ist das Bauen von Images. Die
+Docker-App des UGREEN lehnt den Einhängepunkt `/var/run/docker.sock` ab —
+geprüft, indem die Compose-Datei Zeile für Zeile aufgebaut wurde: ohne diese
+eine Zeile wird das Projekt angelegt, mit ihr nicht. Übrig bleiben
+`privileged: true` mit einem Docker-in-Docker-Image oder der Weg über SSH an
+der Oberfläche vorbei. Beide geben dem Runner faktisch Root auf dem NAS.
+
+Deshalb löst der Workflow **nicht** mehr bei jedem Push aus — sonst sammeln
+sich Läufe an, die nie jemand abarbeitet. Er steht auf `workflow_dispatch`
+und lässt sich in Gitea von Hand starten, sobald einmal ein Runner da ist.
 
 ---
 
@@ -253,7 +273,15 @@ keine Stelle, die das könnte.
 
 ## Aktualisieren
 
-Mit Weg A:
+**Zwei Schritte, zwei Maschinen.** Erst baut der Arbeitsrechner die neue
+Fassung und legt sie in die Registry:
+
+```bash
+Tools/image-veroeffentlichen.sh
+```
+
+Dann holt das NAS sie. In der Docker-App genügt das Aktualisieren des
+Projekts; über die Kommandozeile:
 
 ```bash
 docker compose pull && docker compose up -d

server/docker-compose.runner.yml

@@ -1,5 +1,21 @@
 # Ein Gitea-Runner auf dem NAS.
 #
+# **Nicht in Betrieb — und auf einem UGREEN-NAS nicht über die Docker-App
+# anzulegen.** Deren Compose-Prüfung lehnt den Einhängepunkt
+# `/var/run/docker.sock` ab. Nachgewiesen durch Halbieren: dieselbe Datei
+# ohne diese eine Zeile wird angelegt, mit ihr kommt nur „Bitte überprüfen
+# Sie die Konfigurationsinformationen", ohne Angabe eines Grundes.
+#
+# Was bliebe: `gitea/act_runner:latest-dind-rootless` mit `privileged: true`
+# statt des Socket, oder die Datei über SSH ablegen und dort von Hand
+# starten. Beides gibt dem Runner faktisch Root auf dem NAS, und bei einem
+# öffentlichen Repo reicht dann unter Umständen ein fremder Pull Request,
+# um Code darauf auszuführen. Deshalb baut bis auf Weiteres der
+# Arbeitsrechner — siehe `Tools/image-veroeffentlichen.sh`.
+#
+# Die Datei bleibt liegen, damit der Weg beim nächsten Mal nicht noch
+# einmal von vorn untersucht werden muss.
+#
 # **Wozu.** Gitea verteilt Arbeit nur, es baut nicht selbst. Ohne einen
 # registrierten Runner legt es bei jedem Push einen Lauf an, der dann
 # liegenbleibt. Mit diesem hier baut das NAS das Flaro-Image selbst und legt