Michael Schiemer
02e4dc9338
- Add example secret files for `app_key`, `db_user_password`, and `redis_password`. - Introduce `local.vault.yml.example` for Ansible Vault encryption of local secrets. - Create migration and setup scripts for transitioning from `.env.local` to secrets files. - Update `docker-compose.local.yml` to adopt Docker Secrets and `_FILE` pattern for local configurations. - Add deployment playbooks and enhanced logging configurations for local development.
360 lines
8.8 KiB
Markdown
360 lines
8.8 KiB
Markdown
# Plan: Umstrukturierung der lokalen Entwicklungsumgebung nach Stack-Pattern
|
|
|
|
**Datum**: 2025-11-04
|
|
**Ziel**: Lokale Entwicklungsumgebung in `deployment/stacks/local/` strukturieren, konsistent mit `application` und `staging` Stacks
|
|
|
|
## Aktuelle Struktur
|
|
|
|
### Root-Level (aktuell)
|
|
```
|
|
Repository Root/
|
|
??? docker-compose.base.yml # Gemeinsame Basis
|
|
??? docker-compose.local.yml # Local Override
|
|
??? docker-compose.staging.yml # Staging Override (im Root)
|
|
??? docker-compose.production.yml # Production Override (im Root)
|
|
??? secrets/ # (neu, f?r lokale Secrets)
|
|
```
|
|
|
|
### Stacks-Struktur (aktuell)
|
|
```
|
|
deployment/stacks/
|
|
??? application/ # Production Stack
|
|
? ??? docker-compose.yml # Vollst?ndige Definition
|
|
? ??? README.md
|
|
??? staging/ # Staging Stack (nur nginx config)
|
|
? ??? nginx/conf.d/
|
|
? ??? README.md
|
|
??? postgresql/ # PostgreSQL Stack
|
|
??? docker-compose.yml
|
|
```
|
|
|
|
## Zielstruktur
|
|
|
|
### Root-Level (nach Migration)
|
|
```
|
|
Repository Root/
|
|
??? docker-compose.base.yml # Gemeinsame Basis (bleibt)
|
|
??? docker-compose.staging.yml # Staging Override (bleibt im Root)
|
|
??? docker-compose.production.yml # Production Override (bleibt im Root)
|
|
??? docker-compose.postgres-override.yml # (bleibt)
|
|
```
|
|
|
|
### Stacks-Struktur (nach Migration)
|
|
```
|
|
deployment/stacks/
|
|
??? application/ # Production Stack
|
|
? ??? docker-compose.yml
|
|
? ??? README.md
|
|
??? staging/ # Staging Stack
|
|
? ??? nginx/conf.d/
|
|
? ??? README.md
|
|
??? local/ # Local Development Stack (NEU)
|
|
? ??? docker-compose.yml # Vollst?ndige Local-Konfiguration
|
|
? ??? secrets/ # Lokale Secrets
|
|
? ? ??? redis_password.txt.example
|
|
? ? ??? db_user_password.txt.example
|
|
? ? ??? app_key.txt.example
|
|
? ??? scripts/ # Helper-Scripts
|
|
? ? ??? setup-secrets.sh
|
|
? ? ??? migrate-env-to-secrets.sh
|
|
? ??? README.md # Local Development Dokumentation
|
|
??? postgresql/
|
|
??? docker-compose.yml
|
|
```
|
|
|
|
## Vorteile der Umstrukturierung
|
|
|
|
### 1. Konsistenz
|
|
- ? **Gleiche Struktur** wie `application` und andere Stacks
|
|
- ? **Klare Trennung** der Umgebungen
|
|
- ? **Einheitliches Pattern** f?r alle Stacks
|
|
|
|
### 2. Organisation
|
|
- ? **Lokale Konfiguration** klar als "Stack" erkennbar
|
|
- ? **Secrets lokal** verwaltet (nicht im Root)
|
|
- ? **Helper-Scripts** am richtigen Ort
|
|
|
|
### 3. Wartbarkeit
|
|
- ? **Einheitliche Struktur** erleichtert Wartung
|
|
- ? **Klare Verantwortlichkeiten** pro Stack
|
|
- ? **Einfachere Navigation** f?r Entwickler
|
|
|
|
### 4. Deployment-Konsistenz
|
|
- ? **Gleiche Kommandos** f?r alle Stacks
|
|
- ? **Einheitliche Dokumentation**
|
|
- ? **Konsistente Pfade**
|
|
|
|
## Implementierungsplan
|
|
|
|
### Phase 1: Verzeichnisstruktur erstellen
|
|
|
|
```bash
|
|
mkdir -p deployment/stacks/local/secrets
|
|
mkdir -p deployment/stacks/local/scripts
|
|
chmod 700 deployment/stacks/local/secrets
|
|
```
|
|
|
|
### Phase 2: docker-compose.yml migrieren
|
|
|
|
**Von**: `docker-compose.base.yml + docker-compose.local.yml` (Root)
|
|
**Nach**: `deployment/stacks/local/docker-compose.yml` (vollst?ndige Definition)
|
|
|
|
**Struktur**:
|
|
```yaml
|
|
# deployment/stacks/local/docker-compose.yml
|
|
# Local Development Stack
|
|
# Usage: docker compose -f deployment/stacks/local/docker-compose.yml up
|
|
|
|
services:
|
|
web:
|
|
# ... (aus base.yml + local.yml kombiniert)
|
|
|
|
php:
|
|
# ... mit Secrets und *_FILE Pattern
|
|
|
|
redis:
|
|
# ... mit Passwort (Docker Secrets)
|
|
|
|
# ... weitere Services
|
|
|
|
secrets:
|
|
# ... lokale Secrets
|
|
|
|
networks:
|
|
# ... lokale Netzwerke
|
|
```
|
|
|
|
### Phase 3: Secrets-Verwaltung
|
|
|
|
**Struktur**:
|
|
```
|
|
deployment/stacks/local/
|
|
??? secrets/
|
|
? ??? redis_password.txt.example # Beispiel
|
|
? ??? db_user_password.txt.example # Beispiel
|
|
? ??? app_key.txt.example # Beispiel
|
|
??? .gitignore # secrets/*.txt
|
|
```
|
|
|
|
**Secrets-Pfade in docker-compose.yml**:
|
|
```yaml
|
|
secrets:
|
|
redis_password:
|
|
file: ./secrets/redis_password.txt
|
|
external: false
|
|
```
|
|
|
|
### Phase 4: Helper-Scripts
|
|
|
|
**scripts/setup-secrets.sh**:
|
|
```bash
|
|
#!/bin/bash
|
|
# Setup local development secrets
|
|
cd "$(dirname "$0")/.." # Zu deployment/stacks/local/
|
|
# ... Secrets generieren
|
|
```
|
|
|
|
**scripts/migrate-env-to-secrets.sh**:
|
|
```bash
|
|
#!/bin/bash
|
|
# Migriert Secrets aus .env.local zu secrets/
|
|
cd "$(dirname "$0")/.." # Zu deployment/stacks/local/
|
|
# ... Migration durchf?hren
|
|
```
|
|
|
|
### Phase 5: Dokumentation
|
|
|
|
**deployment/stacks/local/README.md**:
|
|
- Setup-Anleitung
|
|
- Secrets-Verwaltung
|
|
- Verwendung
|
|
- Troubleshooting
|
|
|
|
## Vergleich der Ans?tze
|
|
|
|
### Ansatz A: Vollst?ndige docker-compose.yml (empfohlen)
|
|
|
|
**Struktur**:
|
|
```yaml
|
|
# deployment/stacks/local/docker-compose.yml
|
|
# Vollst?ndige Definition (wie application Stack)
|
|
services:
|
|
web: ...
|
|
php: ...
|
|
redis: ...
|
|
```
|
|
|
|
**Vorteile**:
|
|
- ? Konsistent mit `application` Stack
|
|
- ? Vollst?ndige Kontrolle
|
|
- ? Keine Abh?ngigkeit von Root-Level base.yml
|
|
|
|
**Nachteile**:
|
|
- ?? Etwas mehr Code-Duplikation (aber klar getrennt)
|
|
|
|
### Ansatz B: Base + Override Pattern (wie Staging)
|
|
|
|
**Struktur**:
|
|
```yaml
|
|
# deployment/stacks/local/docker-compose.base.yml (oder Link)
|
|
# deployment/stacks/local/docker-compose.local.yml
|
|
```
|
|
|
|
**Vorteile**:
|
|
- ? Weniger Duplikation
|
|
- ? Konsistent mit Staging-Pattern
|
|
|
|
**Nachteile**:
|
|
- ?? Pfad-Abh?ngigkeiten (base.yml muss relativ erreichbar sein)
|
|
- ?? Komplexer bei verschiedenen Pfaden
|
|
|
|
## Empfehlung: Ansatz A (Vollst?ndige Definition)
|
|
|
|
**Begr?ndung**:
|
|
1. **Konsistenz**: Gleiche Struktur wie `application` Stack
|
|
2. **Autonomie**: Local Stack ist vollst?ndig unabh?ngig
|
|
3. **Klarheit**: Alles in einem Verzeichnis
|
|
4. **Einfachheit**: Keine Pfad-Abh?ngigkeiten
|
|
|
|
## Detaillierte Struktur
|
|
|
|
### deployment/stacks/local/docker-compose.yml
|
|
|
|
**Enth?lt**:
|
|
- Alle Services aus `docker-compose.base.yml` + `docker-compose.local.yml`
|
|
- Redis mit Passwort (Docker Secrets)
|
|
- `*_FILE` Pattern f?r alle Secrets
|
|
- Lokale Ports (8888:80, 443:443, 5433:5432)
|
|
- Host-Mounts f?r Entwicklung
|
|
- Debug-Flags
|
|
|
|
**Services**:
|
|
- `web` (Nginx)
|
|
- `php` (PHP-FPM)
|
|
- `db` (PostgreSQL)
|
|
- `redis` (mit Passwort)
|
|
- `queue-worker`
|
|
- `minio` (optional)
|
|
|
|
### deployment/stacks/local/secrets/
|
|
|
|
**Dateien**:
|
|
- `redis_password.txt` (gitignored)
|
|
- `db_user_password.txt` (gitignored)
|
|
- `app_key.txt` (gitignored)
|
|
- `*.example` (versioniert, als Beispiele)
|
|
|
|
### deployment/stacks/local/scripts/
|
|
|
|
**Scripts**:
|
|
- `setup-secrets.sh` - Generiert Secrets f?r neue Entwickler
|
|
- `migrate-env-to-secrets.sh` - Migriert bestehende .env.local
|
|
- `redis-cli.sh` - Helper f?r Redis-CLI mit Passwort
|
|
|
|
## Migration
|
|
|
|
### Schritt 1: Neue Struktur erstellen
|
|
```bash
|
|
mkdir -p deployment/stacks/local/{secrets,scripts}
|
|
```
|
|
|
|
### Schritt 2: docker-compose.yml erstellen
|
|
- Kombiniere `docker-compose.base.yml` + `docker-compose.local.yml`
|
|
- F?ge Secrets-Konfiguration hinzu
|
|
- F?ge Redis-Passwort hinzu
|
|
|
|
### Schritt 3: Secrets migrieren
|
|
- Erstelle `secrets/` Verzeichnis
|
|
- Generiere oder migriere Secrets
|
|
- Erstelle Beispiel-Dateien
|
|
|
|
### Schritt 4: Scripts erstellen
|
|
- Setup-Script
|
|
- Migration-Script
|
|
- Helper-Scripts
|
|
|
|
### Schritt 5: Dokumentation
|
|
- README.md erstellen
|
|
- ENV_SETUP.md aktualisieren
|
|
- Haupt-README aktualisieren
|
|
|
|
### Schritt 6: Alte Dateien entfernen
|
|
- `docker-compose.local.yml` im Root (nach Migration)
|
|
- Root-Level `secrets/` (falls vorhanden)
|
|
|
|
## Verwendung nach Migration
|
|
|
|
### Vorher (aktuell)
|
|
```bash
|
|
docker compose -f docker-compose.base.yml -f docker-compose.local.yml up
|
|
```
|
|
|
|
### Nachher (neu)
|
|
```bash
|
|
cd deployment/stacks/local
|
|
docker compose up -d
|
|
```
|
|
|
|
**Oder vom Root**:
|
|
```bash
|
|
docker compose -f deployment/stacks/local/docker-compose.yml up -d
|
|
```
|
|
|
|
## Vorteile dieser Struktur
|
|
|
|
1. ? **Konsistenz**: Gleiche Struktur wie `application` Stack
|
|
2. ? **Autonomie**: Local Stack ist vollst?ndig unabh?ngig
|
|
3. ? **Organisation**: Alles Local-Development in einem Verzeichnis
|
|
4. ? **Klarheit**: Klare Trennung der Umgebungen
|
|
5. ? **Wartbarkeit**: Einfacher zu warten und zu erweitern
|
|
|
|
## Nachteile / ?berlegungen
|
|
|
|
### 1. Pfad-Abh?ngigkeiten
|
|
- ?? **Build-Kontexte**: M?ssen relativ zum Repository-Root sein
|
|
- **L?sung**: Absolute Pfade oder `context: ../..` verwenden
|
|
|
|
### 2. Migration
|
|
- ?? **Bestehende Entwickler** m?ssen umstellen
|
|
- **L?sung**: Migration-Script und Dokumentation
|
|
|
|
### 3. Docker Compose Befehle
|
|
- ?? **Andere Pfade** als bisher
|
|
- **L?sung**: Helper-Script oder Makefile-Target
|
|
|
|
## Alternative: Makefile-Targets
|
|
|
|
**Makefile hinzuf?gen**:
|
|
```makefile
|
|
local-up:
|
|
cd deployment/stacks/local && docker compose up -d
|
|
|
|
local-down:
|
|
cd deployment/stacks/local && docker compose down
|
|
|
|
local-logs:
|
|
cd deployment/stacks/local && docker compose logs -f
|
|
|
|
local-ps:
|
|
cd deployment/stacks/local && docker compose ps
|
|
```
|
|
|
|
**Verwendung**:
|
|
```bash
|
|
make local-up
|
|
make local-logs
|
|
make local-ps
|
|
```
|
|
|
|
## N?chste Schritte
|
|
|
|
1. ? Plan erstellt
|
|
2. ? Diskussion: Ist Stack-Struktur gew?nscht?
|
|
3. ? Implementierung: Verzeichnisstruktur erstellen
|
|
4. ? docker-compose.yml migrieren und anpassen
|
|
5. ? Secrets-System implementieren
|
|
6. ? Scripts erstellen
|
|
7. ? Dokumentation
|
|
8. ? Testing
|
|
9. ? Alte Dateien entfernen
|