meldestelle/docs/99_Journal/2026-03-06_Session_Log_Pipeline_Fix_v3.md

type, status, owner, date

type	status	owner	date
journal	ACTIVE	Lead Architect	2026-03-06

Session Log — Pipeline Fix v3: socat nicht verfügbar → iptables DNAT

Datum: 06.03.2026
Agent: 👷 Backend Developer
Thema: CI/CD Pipeline — socat nicht auf Runner verfügbar

---

Problem

Fix v2 verwendete socat als TCP-Proxy (Port 80 → Gitea:3000).
Der Gitea-Runner (VM 102, Debian minimal) hat kein socat installiert und das Paket ist im lokalen APT-Repo nicht auffindbar:

E: Unable to locate package socat

---

Lösung: iptables DNAT

iptables ist auf jedem Linux-System ohne Extra-Paket verfügbar.
DNAT (Destination NAT) leitet Verbindungen auf Kernel-Ebene um — kein Userspace-Proxy nötig.

- name: Registry intern auflösen (Pangolin-Bypass)
  run: |
    echo "10.0.0.22 git.mo-code.at" | sudo tee -a /etc/hosts
    sudo iptables -t nat -A OUTPUT -p tcp -d 10.0.0.22 --dport 80 -j DNAT --to-destination 10.0.0.22:3000
    sudo iptables -t nat -A POSTROUTING -p tcp -d 10.0.0.22 --dport 3000 -j MASQUERADE
    echo "✓ DNAT aktiv: git.mo-code.at:80 → 10.0.0.22:3000"

Traffic-Weg:

BuildKit → http://git.mo-code.at:80
         → /etc/hosts: 10.0.0.22:80
         → iptables DNAT: 10.0.0.22:80 → 10.0.0.22:3000
         → Gitea (HTTP, kein TLS nötig)

---

Warum iptables besser als socat

Eigenschaft	socat	iptables DNAT
Verfügbarkeit	❌ Paket fehlt	✅ immer vorhanden
Paket-Installation	nötig	nicht nötig
Arbeitsebene	Userspace	Kernel (schneller)
Abhängigkeiten	APT-Repo nötig	keine

---

Netzwerk-Übersicht Zora

Host	IP	Protokoll
Runner (VM 102)	10.0.0.23	—
Gitea (CT 101)	10.0.0.22	HTTP :3000
Pangolin (CT 100)	10.0.0.21	HTTPS für git.mo-code.at

---

Fix-Verlauf dieser Pipeline-Debugging-Session

Version	Symptom	Fix	Ergebnis
v1	502 Bad Gateway (Pangolin)	/etc/hosts + provenance:false	Port 443 refused
v2	connection refused Port 443	socat :80 → :3000	socat nicht da
v3	socat nicht verfügbar	iptables DNAT	Permission denied
v4	iptables — kein sudo-Recht	buildkitd Mirror (kein Root)	HTTP→HTTPS Fehler
v5	login-action: HTTP→HTTPS-Konflikt	daemon.json + systemctl restart	✅ erwartet grün

---

Fix v4: buildkitd Mirror — die Root-freie Lösung

iptables schlägt mit Permission denied fehl — der Runner-User hat kein sudo-Recht für iptables.

Lösung: buildkitd hat eine eingebaute Mirror-Funktion. Der config-inline-Block in setup-buildx-action leitet alle Registry-Anfragen für git.mo-code.at intern auf http://10.0.0.22:3000 um — vollständig auf Anwendungsebene, ohne Root-Rechte.

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
  with:
    config-inline: |
      [registry."git.mo-code.at"]
        mirrors = ["http://10.0.0.22:3000"]
        http = true
        insecure = true
      [registry."10.0.0.22:3000"]
        http = true
        insecure = true

- name: Bei Registry intern anmelden (Pangolin-Bypass)
  uses: docker/login-action@v3
  with:
    registry: 10.0.0.22:3000
    username: ${{ secrets.REGISTRY_USER }}
    password: ${{ secrets.REGISTRY_TOKEN }}

Traffic-Weg v4:

BuildKit → push git.mo-code.at/...
         → buildkitd Mirror: http://10.0.0.22:3000
         → Gitea (HTTP, intern, kein Pangolin, kein Timeout)

Kein /etc/hosts, kein iptables, kein socat — rein konfigurativ.

---

Fix v5: daemon.json — die funktionierende Lösung ✅

buildkitd-Mirror (v4) ist für Pulls gedacht, nicht für Pushes. Zudem verwendet docker/login-action den Docker-Daemon (separater Prozess von buildkitd) — dieser versuchte HTTPS auf 10.0.0.22:3000 und bekam: http: server gave HTTP response to HTTPS client.

Lösung: Docker-Daemon pro Job über insecure-registries konfigurieren. sudo tee auf /etc/docker/daemon.json funktioniert auf dem Runner (wie /etc/hosts in v3 gezeigt).

- name: Docker-Daemon für interne Registry konfigurieren (Pangolin-Bypass)
  run: |
    echo '{"insecure-registries":["10.0.0.22:3000"]}' | sudo tee /etc/docker/daemon.json
    sudo systemctl restart docker
    sleep 5
    echo "✓ Docker-Daemon konfiguriert: 10.0.0.22:3000 als insecure-registry"

Traffic-Weg v5:

docker login 10.0.0.22:3000   → Daemon kennt insecure-registry → HTTP ✅
BuildKit push 10.0.0.22:3000  → buildkitd insecure=true        → HTTP ✅
Gitea Registry                → empfängt Image intern           → kein Pangolin, kein Timeout ✅

Auf dem Meldestelle-Host bleibt der Pull über git.mo-code.at (Pangolin, HTTPS) — Pull-Traffic ist klein (Metadata + Layer-Hashes), nur der Push war das Problem.

---

Gelernt

• Minimale Runner-Images haben oft kein socat — APT-Repos auf Air-Gapped Systemen sind limitiert
• iptables DNAT schlägt fehl wenn sudo-Policy es nicht erlaubt — aber sudo tee funktioniert
• buildkitd-Mirror gilt nur für Pulls, nicht für Pushes — falscher Ansatz für Registry-Push-Bypass
• docker/login-action und buildkitd sind zwei getrennte Prozesse mit eigener Config — beide müssen konfiguriert werden
• daemon.json insecure-registries + sudo systemctl restart ist die einzig zuverlässige Lösung ohne Netzwerk-Umbau