Fix: Nachbesserungen aus Code-Review am Cache-Setup

- Healthcheck für den Cache-Server, damit der Runner (depends_on:
  condition: service_healthy) wirklich wartet, bis der Cache-Server auf
  Port 8088 Verbindungen annimmt, statt nur den Container-Start abzuwarten
- Veralteten Kommentarverweis auf "cache-config.yaml" korrigiert zu
  "config/cache.yaml"
- README: Hinweis ergänzt, dass Port 8088 zwingend auf allen
  Host-Interfaces lauschen muss (sonst für Job-Container unerreichbar) und
  daher per Host-Firewall gegen Zugriff von außen abgesichert werden sollte

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014kFWpJ4p1jQ2pJf3S13FWE

.gitignore

@@ -1,4 +1,5 @@
 data/
+cache-secret
 
 .vscode
 .env

README.md

@@ -1,3 +1,71 @@
 # gitea_runner
 
-Enthält eine einfache docker-compose, um einen gitea_runner zu starten. 
+Enthält eine einfache docker-compose, um einen gitea_runner zu starten.
+
+## Verzeichnisstruktur
+
+- `config/runner.yaml` — Konfiguration des Runners
+- `config/cache.yaml` — Konfiguration des Cache-Servers
+- `data/runner` — persistenter Zustand des Runners (u. a. `.runner`-Registrierungsdatei)
+- `data/cache` — persistente Cache-Daten
+- `cache-secret` — gemeinsames Secret für Runner ↔ Cache-Server (siehe unten, **nicht** in Git)
+
+## Einrichtung
+
+Vor dem ersten Start muss auf dem Host ein Secret für die Authentifizierung zwischen
+Runner und Cache-Server erzeugt werden:
+
+```sh
+openssl rand -hex 32 > cache-secret
+chmod 600 cache-secret
+```
+
+Diese Datei darf **nicht committet werden** (sie ist über `.gitignore` ausgeschlossen)
+und muss auf jedem Host, auf dem dieses Setup läuft, individuell erzeugt werden.
+
+## Migration von einer älteren Version dieses Compose-Setups
+
+Frühere Versionen legten die Runner-Daten direkt unter `./data` ab und hatten kein
+`config/`-Verzeichnis. Beim Umstieg auf diese Version muss der bestehende Datenordner
+verschoben werden, sonst registriert sich der Runner erneut (verwaiste Registrierung
+auf der Gitea-Instanz) und der bisherige Cache geht verloren:
+
+```sh
+# Runner vorher stoppen
+docker compose down
+
+# Repository pullen
+git pull
+
+# Vorhandene Daten (u. a. die .runner-Datei) nach data/runner verschieben
+mv data data_old
+mkdir -p data
+mv data_old data/runner
+
+# Danach ganz normal wieder starten
+docker compose up -d
+```
+
+Falls vorher schon ein eigenständiger Cache-Ordner existierte (z. B. unter
+`data/runner/cache` oder `cache-data/` aus einer Zwischenversion), diesen entsprechend
+nach `data/cache` verschieben.
+
+## Cache-Service
+
+Der Cache läuft als eigener Service (`cache` in `docker-compose.yaml`), getrennt vom
+Runner, damit die bis zu 5 parallel laufenden Jobs weiterhin jeweils ihr eigenes,
+isoliertes Docker-Netzwerk bekommen und sich nicht gegenseitig erreichen können.
+Job-Container erreichen den Cache-Server trotzdem über den Docker-Host (`cachehost`
+wird per `--add-host=cachehost:host-gateway` auf das Host-Gateway gemappt, siehe
+`config/runner.yaml` -> `container.options`), der Port `8088` des Cache-Servers ist
+dafür auf dem Host veröffentlicht.
+
+**Achtung:** Da Job-Container den Cache-Server nur über den Host erreichen können,
+muss Port `8088` auf allen Host-Interfaces lauschen (`0.0.0.0`) — eine engere Bindung
+(z. B. nur `127.0.0.1`) würde den Cache für Jobs unerreichbar machen. Der Zugriff ist
+zwar durch das Secret in `cache-secret` geschützt, trotzdem sollte Port `8088` per
+Host-Firewall von außen (Internet/fremdes LAN) blockiert werden, z. B.:
+
+```sh
+ufw deny 8088/tcp
+```

config/cache.yaml

@@ -0,0 +1,5 @@
+cache:
+  dir: /data
+  host: "0.0.0.0"
+  port: 8088
+  external_secret_file: "/run/cache-secret"

config/runner.yaml

@@ -0,0 +1,19 @@
+runner:
+  # Bis zu 5 Jobs gleichzeitig. container.network bleibt leer, damit jeder Job weiterhin
+  # sein eigenes isoliertes Docker-Netzwerk bekommt (kein gegenseitiger Zugriff der Jobs).
+  capacity: 5
+
+cache:
+  enabled: true
+  # Dedizierter, separater Cache-Server (siehe config/cache.yaml + docker-compose.yaml,
+  # Service "cache"), erreichbar über den Docker-Host-Gateway (siehe container.options
+  # unten), unabhängig vom isolierten Netzwerk des jeweiligen Jobs.
+  external_server: "http://cachehost:8088/"
+  external_secret_file: "/run/cache-secret"
+
+container:
+  # Jeder Job bekommt ein eigenes, frisches Docker-Netzwerk (network bewusst leer gelassen),
+  # damit parallele Jobs sich nicht gegenseitig erreichen können. Damit die Job-Container
+  # trotzdem den externen Cache-Server erreichen, wird "cachehost" auf das Docker-Host-Gateway
+  # gemappt; der Cache-Server veröffentlicht seinen Port auf dem Host (siehe docker-compose.yaml).
+  options: "--add-host=cachehost:host-gateway"

docker-compose.yaml

@@ -1,6 +1,11 @@
 services:
   runner:
     image: docker.io/gitea/runner:latest
+    container_name: gitea_runner
+    restart: unless-stopped
+    depends_on:
+      cache:
+        condition: service_healthy
     environment:
       CONFIG_FILE: /config.yaml
       GITEA_INSTANCE_URL: "${INSTANCE_URL}"
@@ -8,6 +13,28 @@ services:
       GITEA_RUNNER_NAME: "${RUNNER_NAME}"
       GITEA_RUNNER_LABELS: "${RUNNER_LABELS}"
     volumes:
-      - ./config.yaml:/config.yaml
-      - ./data:/data
+      - ./config/runner.yaml:/config.yaml
+      - ./data/runner:/data
+      - ./cache-secret:/run/cache-secret:ro
       - /var/run/docker.sock:/var/run/docker.sock
+    extra_hosts:
+      - "cachehost:host-gateway"
+
+  cache:
+    image: docker.io/gitea/runner:latest
+    container_name: gitea_runner_cache
+    restart: unless-stopped
+    entrypoint: ["/sbin/tini", "--", "/usr/local/bin/gitea-runner"]
+    command: ["-c", "/config.yaml", "cache-server"]
+    volumes:
+      - ./config/cache.yaml:/config.yaml
+      - ./data/cache:/data
+      - ./cache-secret:/run/cache-secret:ro
+    ports:
+      - "8088:8088"
+    healthcheck:
+      test: ["CMD", "bash", "-c", "echo > /dev/tcp/127.0.0.1/8088"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+      start_period: 5s