michaelschiemer/docs/deployment/shared-postgres-override-plan.md

# Plan: Gemeinsame Docker-Compose Override f?r PostgreSQL-Verbindung

**Datum**: 2025-11-04  
**Ziel**: Gemeinsame Override-Datei f?r Application- und Staging-Stack, die beide mit dem PostgreSQL-Stack verbinden k?nnen

## Aktuelle Situation

### Application Stack (`deployment/stacks/application/docker-compose.yml`)
- ? **Bereits im `app-internal` Netzwerk**
- ? **Kann sich bereits mit PostgreSQL verbinden**
- Services: `app`, `nginx`, `queue-worker`, `scheduler`
- Netzwerk: `app-internal` (external: true)

### Staging Stack (`docker-compose.staging.yml`)
- ? **Nur im `staging-internal` Netzwerk**
- ? **Kann sich NICHT mit PostgreSQL verbinden**
- Services: `staging-app`, `staging-nginx`, `staging-queue-worker`, `staging-scheduler`
- Netzwerk: `staging-internal` (driver: bridge)

### PostgreSQL Stack (`deployment/stacks/postgresql/docker-compose.yml`)
- Service: `postgres`
- Netzwerk: `app-internal` (external: true)

## L?sung: Gemeinsame Override-Datei

### Datei-Struktur

```
Repository Root/
??? docker-compose.base.yml
??? docker-compose.staging.yml
??? docker-compose.postgres-override.yml  # NEU: Gemeinsame Override
??? deployment/
    ??? stacks/
        ??? application/
        ?   ??? docker-compose.yml
        ??? postgresql/
            ??? docker-compose.yml
```

### Vorteile

1. ? **DRY-Prinzip**: Netzwerk-Konfiguration zentral
2. ? **Wartbarkeit**: ?nderungen an einem Ort
3. ? **Konsistenz**: Beide Stacks nutzen identische Konfiguration
4. ? **Flexibilit?t**: Kann einfach aktiviert/deaktiviert werden

## Implementierungsplan

### 1. Neue Datei: `docker-compose.postgres-override.yml`

**Inhalt**: Netzwerk-Definition und Service-Overrides f?r PostgreSQL-Verbindung

```yaml
# Shared PostgreSQL Connection Override
# Usage:
#   Application Stack:
#     docker compose -f deployment/stacks/application/docker-compose.yml \
#                    -f docker-compose.postgres-override.yml up
#
#   Staging Stack:
#     docker compose -f docker-compose.base.yml \
#                    -f docker-compose.staging.yml \
#                    -f docker-compose.postgres-override.yml up

services:
  # Application Stack Services
  app:
    networks:
      app-internal: {}  # Ensure app-internal network is used
  nginx:
    networks:
      app-internal: {}  # Ensure app-internal network is used
  queue-worker:
    networks:
      app-internal: {}  # Ensure app-internal network is used
  scheduler:
    networks:
      app-internal: {}  # Ensure app-internal network is used

  # Staging Stack Services
  staging-app:
    networks:
      app-internal: {}  # Add app-internal network
  staging-queue-worker:
    networks:
      app-internal: {}  # Add app-internal network
  staging-scheduler:
    networks:
      app-internal: {}  # Add app-internal network

networks:
  app-internal:
    external: true
    name: app-internal
```

### 2. Problem: Service-Namen sind unterschiedlich

**Application Stack**: `app`, `nginx`, `queue-worker`, `scheduler`  
**Staging Stack**: `staging-app`, `staging-nginx`, `staging-queue-worker`, `staging-scheduler`

**L?sung**: Die Override-Datei kann beide Service-Namen unterst?tzen (Docker Compose ignoriert nicht-existierende Services).

### 3. Alternative: Zwei separate Override-Dateien

**Option A**: Eine Datei f?r beide (einfacher)
- ? Einfacher zu warten
- ?? Enth?lt Service-Definitionen f?r beide Stacks

**Option B**: Zwei Dateien (sauberer)
- `docker-compose.postgres-override-app.yml` (f?r Application Stack)
- `docker-compose.postgres-override-staging.yml` (f?r Staging Stack)
- ? Klarer getrennt
- ?? Mehr Dateien

**Empfehlung**: Option A - eine Datei, da die Konfiguration identisch ist

## Detaillierte Implementierung

### Datei: `docker-compose.postgres-override.yml`

```yaml
# Shared PostgreSQL Connection Override
#
# This file provides network configuration for connecting to the PostgreSQL Stack.
# It can be used by both Application Stack and Staging Stack.
#
# Usage:
#   Application Stack:
#     docker compose -f deployment/stacks/application/docker-compose.yml \
#                    -f docker-compose.postgres-override.yml up
#
#   Staging Stack:
#     docker compose -f docker-compose.base.yml \
#                    -f docker-compose.staging.yml \
#                    -f docker-compose.postgres-override.yml up
#
# Prerequisites:
#   - PostgreSQL Stack must be running (creates app-internal network)
#   - app-internal network must exist as external network

services:
  # Application Stack Services
  # (These will be ignored if not present in the base compose file)
  app:
    networks:
      app-internal: {}  # Ensure app-internal network is available
  nginx:
    networks:
      app-internal: {}  # Ensure app-internal network is available
  queue-worker:
    networks:
      app-internal: {}  # Ensure app-internal network is available
  scheduler:
    networks:
      app-internal: {}  # Ensure app-internal network is available

  # Staging Stack Services
  # (These will be ignored if not present in the base compose file)
  staging-app:
    networks:
      app-internal: {}  # Add app-internal network for PostgreSQL access
  staging-queue-worker:
    networks:
      app-internal: {}  # Add app-internal network for PostgreSQL access
  staging-scheduler:
    networks:
      app-internal: {}  # Add app-internal network for PostgreSQL access

networks:
  app-internal:
    external: true
    name: app-internal
```

### Wichtig: Netzwerk-Merge-Verhalten

Docker Compose **merged** Netzwerke, wenn ein Service mehrere Netzwerke hat:

```yaml
# In docker-compose.staging.yml
staging-app:
  networks:
    - staging-internal

# In docker-compose.postgres-override.yml
staging-app:
  networks:
    app-internal: {}

# Ergebnis: staging-app ist in BEIDEN Netzwerken
# - staging-internal (aus staging.yml)
# - app-internal (aus override.yml)
```

## Verwendung

### Application Stack

**Aktuell**:
```bash
cd deployment/stacks/application
docker compose -f docker-compose.yml up -d
```

**Mit Override** (optional, da bereits im app-internal Netzwerk):
```bash
cd deployment/stacks/application
docker compose -f docker-compose.yml \
               -f ../../docker-compose.postgres-override.yml up -d
```

### Staging Stack

**Aktuell**:
```bash
docker compose -f docker-compose.base.yml \
               -f docker-compose.staging.yml up -d
```

**Mit Override** (f?r PostgreSQL-Verbindung):
```bash
docker compose -f docker-compose.base.yml \
               -f docker-compose.staging.yml \
               -f docker-compose.postgres-override.yml up -d
```

## Deployment-Skripte anpassen

### Ansible Playbooks

**`deployment/ansible/playbooks/deploy-staging.yml`**:
```yaml
- name: Start staging stack
  command: >
    docker compose
    -f docker-compose.base.yml
    -f docker-compose.staging.yml
    -f docker-compose.postgres-override.yml
    up -d
  args:
    chdir: "{{ staging_deploy_path }}"
```

**`deployment/ansible/playbooks/deploy-production.yml`**:
```yaml
- name: Start application stack
  command: >
    docker compose
    -f docker-compose.yml
    -f ../../docker-compose.postgres-override.yml
    up -d
  args:
    chdir: "{{ app_deploy_path }}/deployment/stacks/application"
```

## Vorteile dieser L?sung

1. ? **Zentrale Konfiguration**: Netzwerk-Setup an einem Ort
2. ? **Wiederverwendbar**: Beide Stacks nutzen die gleiche Datei
3. ? **Optional**: Kann bei Bedarf weggelassen werden
4. ? **Flexibel**: Einfach erweiterbar f?r weitere Services
5. ? **DRY**: Keine Duplikation von Netzwerk-Konfiguration

## Nachteile / ?berlegungen

1. ?? **Pfad-Abh?ngigkeit**: Relative Pfade in verschiedenen Verzeichnissen
   - **L?sung**: Absolute Pfade oder von Repository-Root aus ausf?hren

2. ?? **Service-Namen**: Docker Compose ignoriert nicht-existierende Services
   - **Status**: ? Funktioniert - Docker Compose merged nur existierende Services

3. ?? **Netzwerk muss existieren**: `app-internal` muss vorher erstellt sein
   - **Status**: ? Wird automatisch vom PostgreSQL-Stack erstellt

## Alternative: Inline-Netzwerk-Konfiguration

**Alternativ** k?nnte das Netzwerk auch direkt in den jeweiligen Compose-Dateien definiert werden:

- `docker-compose.staging.yml`: Netzwerk `app-internal` hinzuf?gen
- `deployment/stacks/application/docker-compose.yml`: Bereits vorhanden

**Nachteil**: Duplikation, weniger wartbar

**Vorteil**: Keine zus?tzliche Override-Datei n?tig

## Empfehlung

**Gemeinsame Override-Datei** ist die beste L?sung, weil:
1. **DRY-Prinzip**: Keine Duplikation
2. **Wartbarkeit**: ?nderungen an einem Ort
3. **Flexibilit?t**: Kann optional verwendet werden
4. **Klarheit**: Explizite PostgreSQL-Verbindung sichtbar

## N?chste Schritte

1. ? Plan erstellt
2. ? Implementierung: `docker-compose.postgres-override.yml` erstellen
3. ? Staging Stack: Verwendung in Dokumentation/Deployment-Skripten
4. ? Application Stack: Optional (bereits funktionsf?hig, aber f?r Konsistenz)
5. ? Testing: Beide Stacks mit Override testen
6. ? Dokumentation: README-Dateien aktualisieren