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)	✅ 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.

---

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 (auch bei tee in /etc/hosts erlaubt)
• buildkitd Mirror ist die sauberste Lösung: kein Root, kein Extra-Paket, rein in der Workflow-Konfig
• Login auf 10.0.0.22:3000 (intern) funktioniert mit denselben Gitea-Credentials wie der externe Login