michaelschiemer/docs/deployment/staging-postgres-connection-plan.md

Plan: Verbindung zum PostgreSQL-Stack f?r Staging

Datum: 2025-11-04
Ziel: Staging-Services sollen sich mit dem PostgreSQL-Container aus dem PostgreSQL-Stack verbinden k?nnen

Aktuelle Situation

PostgreSQL-Stack (deployment/stacks/postgresql/docker-compose.yml)

• Service-Name: postgres
• Container-Name: postgres
• Netzwerk: app-internal (external: true)
• Port: 5432

Staging-Stack (docker-compose.staging.yml)

• Netzwerk: staging-internal (driver: bridge, nicht external)
• Problem: staging-app ist nur im staging-internal Netzwerk und kann daher den postgres Container nicht erreichen

Application-Stack (Production) (deployment/stacks/application/docker-compose.yml)

• Netzwerk: app-internal (external: true)
• Status: ? Kann sich mit postgres verbinden (gleiches Netzwerk)

L?sung: Multi-Network-Architektur

Die Staging-Services m?ssen beide Netzwerke nutzen:

1. app-internal (external) - f?r Zugriff auf PostgreSQL-Stack
2. staging-internal (internal) - f?r interne Staging-Services (Redis, etc.)

Implementierungsplan

1. Netzwerk-Konfiguration anpassen

?nderungen in docker-compose.staging.yml:

A. app-internal Netzwerk als external definieren

networks:
  traefik-public:
    external: true
  staging-internal:
    driver: bridge
  app-internal:  # NEU: F?r PostgreSQL-Zugriff
    external: true
    name: app-internal

B. Staging-Services an beide Netzwerke anschlie?en

Services die PostgreSQL ben?tigen:

• staging-app ? app-internal + staging-internal
• staging-queue-worker ? app-internal + staging-internal
• staging-scheduler ? app-internal + staging-internal

Services die KEINE PostgreSQL ben?tigen:

• staging-nginx ? bleibt bei traefik-public + staging-internal
• staging-redis ? bleibt bei staging-internal (nur intern)

2. DB_HOST Konfiguration

Aktuell: DB_HOST=${DB_HOST:-postgres}
Status: ? Korrekt - postgres ist der Service-Name im PostgreSQL-Stack

Keine ?nderung n?tig, da postgres der korrekte Hostname ist, sobald die Services im app-internal Netzwerk sind.

3. Dependencies hinzuf?gen

Optional: depends_on f?r PostgreSQL k?nnte hinzugef?gt werden, aber da der PostgreSQL-Stack extern ist, sollte besser auf Health-Checks verzichtet werden (externer Service kann nicht direkt abh?ngig sein).

Alternative: Warten auf PostgreSQL-Verf?gbarkeit im Entrypoint-Script.

4. Netzwerk-Architektur

???????????????????????????????????????????????????????????
? PostgreSQL Stack (deployment/stacks/postgresql/)        ?
? ??????????????????????????????????????????????????????? ?
? ? postgres Container                                  ? ?
? ? Network: app-internal (external)                    ? ?
? ??????????????????????????????????????????????????????? ?
???????????????????????????????????????????????????????????
                         ?
                         ?
                         ? app-internal (external network)
                         ?
????????????????????????????????????????????????????????????
? Staging Stack (docker-compose.staging.yml)               ?
?                                                           ?
? ????????????????????  ????????????????????            ?
? ? staging-app       ?  ? staging-queue-   ?            ?
? ? Networks:         ?  ? worker           ?            ?
? ? ? app-internal    ?  ? Networks:         ?            ?
? ? ? staging-internal?  ? ? app-internal    ?            ?
? ????????????????????  ? ? staging-internal?            ?
?                        ????????????????????            ?
?                                                           ?
? ????????????????????  ????????????????????            ?
? ? staging-redis    ?  ? staging-nginx    ?            ?
? ? Networks:        ?  ? Networks:         ?            ?
? ? ? staging-       ?  ? ? traefik-public  ?            ?
? ?   internal       ?  ? ? staging-internal?            ?
? ????????????????????  ????????????????????            ?
????????????????????????????????????????????????????????????

Konkrete ?nderungen

Datei: docker-compose.staging.yml

1. Networks-Sektion erweitern

networks:
  traefik-public:
    external: true
  staging-internal:
    driver: bridge
  app-internal:  # NEU: F?r PostgreSQL-Zugriff
    external: true
    name: app-internal

2. staging-app: app-internal Netzwerk hinzuf?gen

staging-app:
  networks:
    - app-internal      # NEU: F?r PostgreSQL
    - staging-internal  # Bestehend: F?r Redis

3. staging-queue-worker: app-internal Netzwerk hinzuf?gen

staging-queue-worker:
  networks:
    - app-internal      # NEU: F?r PostgreSQL
    - staging-internal  # Bestehend: F?r Redis

4. staging-scheduler: app-internal Netzwerk hinzuf?gen

staging-scheduler:
  networks:
    - app-internal      # NEU: F?r PostgreSQL
    - staging-internal  # Bestehend: F?r Redis

Vorteile dieser L?sung

1. ? Keine ?nderung am PostgreSQL-Stack n?tig
2. ? Staging nutzt bestehende PostgreSQL-Infrastruktur
3. ? Isolation bleibt erhalten: Staging-Services kommunizieren intern ?ber staging-internal
4. ? Konsistent mit Production: Production nutzt ebenfalls app-internal
5. ? Minimale ?nderungen: Nur Netzwerk-Konfiguration, keine DB_HOST-?nderung n?tig

Nachteile / ?berlegungen

1. ?? Netzwerk-Abh?ngigkeit: Staging h?ngt von externem app-internal Netzwerk ab

   • L?sung: Netzwerk muss vor Staging-Start existieren (sollte automatisch sein)

2. ?? Shared Database: Staging und Production k?nnten theoretisch die gleiche DB nutzen

   • Aktuell: DB_DATABASE=${DB_DATABASE:-michaelschiemer_staging} verhindert dies
   • Empfehlung: Separate Datenbank f?r Staging (michaelschiemer_staging)

Testing-Schritte nach Implementierung

1. Netzwerk-Verf?gbarkeit pr?fen:

   docker network inspect app-internal | grep postgres
   

2. Container-Verbindung testen:

   docker exec staging-app ping -c 1 postgres
   

3. PostgreSQL-Verbindung testen:

   docker exec staging-app php -r "
   \$dsn = 'pgsql:host=postgres;port=5432;dbname=' . getenv('DB_DATABASE');
   \$pdo = new PDO(\$dsn, getenv('DB_USERNAME'), file_get_contents(getenv('DB_PASSWORD_FILE')));
   echo 'Connection successful: ' . \$pdo->query('SELECT version()')->fetchColumn();
   "
   

4. Application-Logs pr?fen:

   docker logs staging-app | grep -i "database\|postgres\|connection"
   

N?chste Schritte

1. ? Plan erstellt
2. ? Implementierung: Netzwerk-Konfiguration anpassen
3. ? Testing: Verbindung testen
4. ? Dokumentation: README aktualisieren

Alternative Ans?tze (nicht empfohlen)

Alternative 1: Eigener PostgreSQL f?r Staging

• Vorteil: Vollst?ndige Isolation
• Nachteil: Mehr Ressourcen, mehr Wartungsaufwand
• Status: Nicht gew?nscht (Benutzer m?chte PostgreSQL-Stack nutzen)

Alternative 2: Externe PostgreSQL-URL

• Vorteil: Flexibler
• Nachteil: Komplexer, erfordert externe Netzwerk-Konfiguration
• Status: Nicht n?tig (Docker-Netzwerke sind ausreichend)