mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d8c9d11adb
meldestelle/docs/99_Journal/2026-03-10_Session_Log_Keycloak_Hostname_Fix.md

7.1 KiB
Raw Blame History

type status owner last_update
Journal ACTIVE Curator 2026-03-10

Session Log — 2026-03-10: Keycloak Hostname Fix, Git Push Analyse & DOCKER_REGISTRY Fix

Datum: Di. 10. März 2026
Agent: 🧹 Curator / 👷 Backend Developer
Kontext: Folge-Session zu Keycloak-Härtung vom 09.03.2026

Übersicht

# Problem Status
1 Git Push fehlgeschlagen ✅ Analysiert (Netzwerkfehler)
2 Keycloak Admin-Dashboard auf meldestelle-host nicht erreichbar ✅ Root Cause + Fix dokumentiert
3 Alertmanager Permission-Fehler ✅ Identifiziert
4 DOCKER_REGISTRY falsch — Images nicht gefunden ✅ Behoben

Problem 1: Git Push fehlgeschlagen

Zeitpunkt: 2026-03-09 ~15:50 (aus Vortagslogs)

Symptom

fatal: unable to access 'https://git.mo-code.at/mocode-software/meldestelle/'
Failed to connect to git.mo-code.at port 443 after 133648 ms: Could not connect to server

Analyse

Zwei separate Ereignisse wurden fälschlicherweise als ein Problem wahrgenommen:

  1. 15:50 — Push rejected (fetch first): Normaler Git-Fehler, Remote hatte neue Commits.
  • Korrekt gelöst durch: fetch + rebase → Successfully rebased and updated refs/heads/main
  1. 15:51 — Push nach Rebase fehlgeschlagen: Netzwerkfehler — git.mo-code.at:443 war nicht erreichbar ( Pangolin-Tunnel kurzzeitig down).

Lösung

Kein Code-Fix nötig. Sobald der Server wieder erreichbar ist:

curl -I https://git.mo-code.at   # Erreichbarkeit prüfen
git push origin main              # Einfach erneut pushen

Gelernt

Der Rebase war korrekt und vollständig. Kein --force, kein git reset nötig. Pangolin-Tunnel-Ausfälle sind transient — immer zuerst Netzwerk prüfen, bevor Git-Befehle wiederholt werden.

Problem 2: Keycloak Admin-Dashboard auf meldestelle-host nicht erreichbar

Zeitpunkt: 2026-03-10 ~10:17

Symptom

  • Lokal (localhost:8180/admin): ✅ funktioniert
  • Auf meldestelle-host (10.0.0.50:8180/admin): ❌ nicht erreichbar
  • Management-Port (10.0.0.50:9000): ✅ erreichbar

Root Cause: KC_HOSTNAME ohne Port

In der .env auf meldestelle-host:

KC_HOSTNAME=10.0.0.50   # ← Port fehlt!

Keycloak 26.x (hostname v2) interpretiert KC_HOSTNAME als kanonische Basis-URL. Ohne Port-Angabe erwartet Keycloak Requests auf Port 80 (HTTP-Standard). Der tatsächliche Host-Port ist aber 8180 → Mismatch → Admin-Interface antwortet nicht.

Warum Port 9000 funktioniert: Der Management-Port (KC_HTTP_MANAGEMENT_PORT=9000) ist nicht an KC_HOSTNAME gebunden und antwortet unabhängig vom Hostname-Mapping immer.

Warum lokal alles funktioniert:

KC_HOSTNAME=localhost   # Port 8180 → Container-intern 8080 → passt

localhost ohne Port funktioniert, weil der Browser/curl den Port aus der URL übernimmt und Keycloak bei KC_HOSTNAME_STRICT=false toleranter ist.

Zusätzliches Problem: Deprecated Variable

KC_HOSTNAME_STRICT_HTTPS=false   # deprecated seit Keycloak 26.x (hostname v2)

Diese Variable wird in Keycloak 26.x ignoriert — kann zu unerwartetem Verhalten führen.

Fix für .env auf meldestelle-host

# VORHER:
KC_HOSTNAME=10.0.0.50
KC_HOSTNAME_STRICT=false
KC_HOSTNAME_STRICT_HTTPS=false   # deprecated

# NACHHER:
KC_HOSTNAME=10.0.0.50:8180
KC_HOSTNAME_STRICT=false
# KC_HOSTNAME_STRICT_HTTPS entfernt (deprecated in Keycloak 26.x)

Anwendung des Fixes

# Auf meldestelle-host:
nano .env
# KC_HOSTNAME=10.0.0.50  →  KC_HOSTNAME=10.0.0.50:8180
# KC_HOSTNAME_STRICT_HTTPS=false  →  Zeile entfernen

docker compose -f dc-infra.yaml up -d keycloak

# Test nach ~30s:
curl -s http://10.0.0.50:8180/admin/

Gelernt

KC_HOSTNAME in Keycloak 26.x (hostname v2) muss den vollständigen Hostnamen inkl. Port enthalten, wenn kein Standard-Port (80/443) verwendet wird. KC_HOSTNAME_STRICT_HTTPS ist seit Keycloak 26.x deprecated und sollte aus allen .env-Dateien entfernt werden — es wird stillschweigend ignoriert.

Problem 3: Alertmanager Permission-Fehler (Nebenbefund)

Symptom (aus Docker-Logs)

err="open /etc/alertmanager/alertmanager.yaml: permission denied"

Root Cause

Die alertmanager.yaml auf dem Host hat falsche Dateiberechtigungen.

Fix

chmod 644 config/docker/alertmanager/alertmanager.yaml
docker compose -f dc-ops.yaml restart alertmanager

Problem 4: DOCKER_REGISTRY falsch — Images nicht gefunden

Zeitpunkt: 2026-03-10 ~13:20

Symptom

! Image git.mo-code.at/mocode-software/keycloak:latest   manifest unknown
! Image git.mo-code.at/mocode-software/api-gateway:latest manifest unknown
Error response from daemon: No such image: git.mo-code.at/mocode-software/keycloak:latest

docker compose --profile all up -d --no-build schlug fehl — alle custom Images nicht gefunden.

Root Cause: Falscher Registry-Pfad in .env

Die Pipeline (.gitea/workflows/docker-publish.yaml) pusht Images nach:

10.0.0.22:3000/mocode-software/meldestelle/keycloak:latest
                               ^^^^^^^^^^^^

Die .env hatte jedoch:

DOCKER_REGISTRY=git.mo-code.at/mocode-software   # ← /meldestelle fehlt!

Docker suchte also unter git.mo-code.at/mocode-software/keycloak:latest — das /meldestelle/-Segment fehlte.

Fix

Datei Vorher Nachher
.env (lokal) git.mo-code.at/mocode-software git.mo-code.at/mocode-software/meldestelle

Anwendung auf meldestelle-host

nano .env
# DOCKER_REGISTRY=git.mo-code.at/mocode-software
#              ↓
# DOCKER_REGISTRY=git.mo-code.at/mocode-software/meldestelle

docker compose --profile all up -d --no-build

Gelernt

Der Image-Pfad in DOCKER_REGISTRY muss exakt dem Pfad entsprechen, unter dem die Pipeline die Images in die Registry pusht — inklusive aller Namespace-Segmente (/meldestelle/). Beim Einrichten einer neuen Registry immer docker pull <full-image-path> manuell testen, bevor docker compose up --no-build verwendet wird.

Offene Punkte

Punkt Priorität Beschreibung
Keycloak Hostname Fix anwenden 🔴 Hoch .env auf meldestelle-host: KC_HOSTNAME=10.0.0.50:8180
DOCKER_REGISTRY Fix anwenden 🔴 Hoch .env auf meldestelle-host: DOCKER_REGISTRY=...meldestelle
Alertmanager Permission Fix 🟡 Mittel chmod 644 auf alertmanager.yaml
KC_HOSTNAME_STRICT_HTTPS bereinigen 🟢 Niedrig Deprecated Variable aus allen .env-Dateien entfernen