feat(local-secrets): introduce unified local secrets management and documentation
- 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.
This commit is contained in:
470
docs/deployment/local-secrets-unification-plan.md
Normal file
470
docs/deployment/local-secrets-unification-plan.md
Normal file
@@ -0,0 +1,470 @@
|
||||
# Plan: Vereinheitlichung der lokalen Entwicklungsumgebung mit Staging/Production
|
||||
|
||||
**Datum**: 2025-11-04
|
||||
**Ziel**: Lokale Entwicklungsumgebung auf Docker Secrets und Redis-Passwort umstellen, um Konsistenz mit Staging/Production zu erreichen
|
||||
|
||||
## Aktuelle Situation
|
||||
|
||||
### Lokal (docker-compose.local.yml)
|
||||
- ? **Redis**: Kein Passwort (nur redis.conf)
|
||||
- ? **Docker Secrets**: Nicht verwendet
|
||||
- ? ***_FILE Pattern**: Nicht verwendet
|
||||
- ? **Secrets**: Direkt in `.env.local` (plain text)
|
||||
|
||||
### Staging/Production
|
||||
- ? **Redis**: Mit Passwort via Docker Secrets
|
||||
- ? **Docker Secrets**: Aktiviert
|
||||
- ? ***_FILE Pattern**: F?r alle Secrets
|
||||
- ? **Framework**: `DockerSecretsResolver` unterst?tzt automatisch `*_FILE` Pattern
|
||||
|
||||
## Vorteile der Vereinheitlichung
|
||||
|
||||
### 1. Konsistenz
|
||||
- ? **Gleiche Konfiguration** in allen Umgebungen
|
||||
- ? **Weniger ?berraschungen** bei Deployment
|
||||
- ? **Einfachere Fehlersuche** (gleiche Konfiguration = gleiche Probleme)
|
||||
|
||||
### 2. Framework-Support
|
||||
- ? **Framework unterst?tzt bereits `DockerSecretsResolver`**
|
||||
- ? **Automatisches Laden** von `*_FILE` Pattern
|
||||
- ? **Kein Code-Change n?tig** - nur Konfiguration
|
||||
|
||||
### 3. Sicherheit
|
||||
- ? **Bessere Praxis** auch in Entwicklung
|
||||
- ? **Secrets nicht in `.env.local`** (kann versehentlich committed werden)
|
||||
- ? **Dateisystem-Permissions** f?r Secrets
|
||||
|
||||
### 4. Entwickler-Erfahrung
|
||||
- ? **Testen mit Production-?hnlicher Konfiguration**
|
||||
- ? **Fr?hes Erkennen** von Secrets-Problemen
|
||||
- ? **Einheitliches Setup** f?r alle Entwickler
|
||||
|
||||
## Nachteile / ?berlegungen
|
||||
|
||||
### 1. Komplexit?t
|
||||
- ?? **Mehr Setup-Schritte** f?r neue Entwickler
|
||||
- ?? **Zus?tzliche Secrets-Dateien** m?ssen erstellt werden
|
||||
- ?? **Lokale Secrets-Verwaltung** n?tig
|
||||
|
||||
### 2. Migration
|
||||
- ?? **Bestehende `.env.local`** muss angepasst werden
|
||||
- ?? **Secrets-Verzeichnis** muss erstellt werden
|
||||
- ?? **Dokumentation** muss aktualisiert werden
|
||||
|
||||
## Implementierungsplan
|
||||
|
||||
### Phase 1: Secrets-Verzeichnis und Struktur
|
||||
|
||||
#### 1.1 Secrets-Verzeichnis erstellen
|
||||
```bash
|
||||
mkdir -p secrets
|
||||
chmod 700 secrets
|
||||
```
|
||||
|
||||
#### 1.2 .gitignore aktualisieren
|
||||
```gitignore
|
||||
# Secrets (lokal)
|
||||
secrets/*.txt
|
||||
!secrets/*.example
|
||||
```
|
||||
|
||||
#### 1.3 Beispiel-Secrets erstellen
|
||||
```bash
|
||||
# secrets/redis_password.txt.example
|
||||
# Beispiel: local-dev-redis-password-2024
|
||||
|
||||
# secrets/db_user_password.txt.example
|
||||
# Beispiel: local-dev-db-password-2024
|
||||
|
||||
# secrets/app_key.txt.example
|
||||
# Beispiel: base64:local-dev-app-key-generated
|
||||
```
|
||||
|
||||
### Phase 2: Docker Compose Konfiguration
|
||||
|
||||
#### 2.1 docker-compose.local.yml aktualisieren
|
||||
|
||||
**Redis Service:**
|
||||
```yaml
|
||||
redis:
|
||||
secrets:
|
||||
- redis_password
|
||||
command: >
|
||||
sh -c "redis-server
|
||||
--requirepass $$(cat /run/secrets/redis_password)
|
||||
--maxmemory 256mb
|
||||
--maxmemory-policy allkeys-lru
|
||||
--save 900 1
|
||||
--save 300 10
|
||||
--save 60 10000
|
||||
--appendonly yes
|
||||
--appendfsync everysec"
|
||||
healthcheck:
|
||||
test: ["CMD", "sh", "-c", "redis-cli --no-auth-warning -a $$(cat /run/secrets/redis_password) ping"]
|
||||
```
|
||||
|
||||
**PHP Service:**
|
||||
```yaml
|
||||
php:
|
||||
environment:
|
||||
- REDIS_PASSWORD_FILE=/run/secrets/redis_password
|
||||
- DB_PASSWORD_FILE=/run/secrets/db_user_password
|
||||
- APP_KEY_FILE=/run/secrets/app_key
|
||||
secrets:
|
||||
- redis_password
|
||||
- db_user_password
|
||||
- app_key
|
||||
```
|
||||
|
||||
**Queue-Worker Service:**
|
||||
```yaml
|
||||
queue-worker:
|
||||
environment:
|
||||
- REDIS_PASSWORD_FILE=/run/secrets/redis_password
|
||||
- DB_PASSWORD_FILE=/run/secrets/db_user_password
|
||||
secrets:
|
||||
- redis_password
|
||||
- db_user_password
|
||||
```
|
||||
|
||||
#### 2.2 docker-compose.base.yml Secrets erweitern
|
||||
|
||||
**Secrets-Sektion:**
|
||||
```yaml
|
||||
secrets:
|
||||
db_user_password:
|
||||
file: ./secrets/db_user_password.txt
|
||||
external: false
|
||||
redis_password:
|
||||
file: ./secrets/redis_password.txt
|
||||
external: false
|
||||
app_key:
|
||||
file: ./secrets/app_key.txt
|
||||
external: false
|
||||
```
|
||||
|
||||
**Hinweis**: `external: false` bedeutet, dass die Dateien lokal sein m?ssen (nicht external wie in Production).
|
||||
|
||||
### Phase 3: Redis-Konfiguration
|
||||
|
||||
#### 3.1 redis.conf anpassen
|
||||
**Option A**: redis.conf entfernt (nur Command-Line-Args)
|
||||
**Option B**: redis.conf mit requirepass (aus Secret geladen)
|
||||
|
||||
**Empfehlung**: Option A - Command-Line-Args sind flexibler und konsistenter mit Staging/Production.
|
||||
|
||||
#### 3.2 redis.conf entfernen oder anpassen
|
||||
```ini
|
||||
# docker/redis/redis.conf
|
||||
# Hinweis: Passwort wird via Command-Line-Args gesetzt (aus Docker Secret)
|
||||
# requirepass wird nicht hier gesetzt, sondern via --requirepass Argument
|
||||
```
|
||||
|
||||
### Phase 4: Migration bestehender .env.local
|
||||
|
||||
#### 4.1 Secrets aus .env.local extrahieren
|
||||
```bash
|
||||
# Script: scripts/migrate-env-to-secrets.sh
|
||||
#!/bin/bash
|
||||
|
||||
SECRETS_DIR="./secrets"
|
||||
mkdir -p "$SECRETS_DIR"
|
||||
|
||||
# Redis Password
|
||||
if grep -q "REDIS_PASSWORD=" .env.local; then
|
||||
grep "REDIS_PASSWORD=" .env.local | cut -d'=' -f2 > "$SECRETS_DIR/redis_password.txt"
|
||||
chmod 600 "$SECRETS_DIR/redis_password.txt"
|
||||
echo "? Created secrets/redis_password.txt"
|
||||
# Entferne aus .env.local (kommentiere aus oder entferne)
|
||||
sed -i '/^REDIS_PASSWORD=/d' .env.local
|
||||
fi
|
||||
|
||||
# DB Password
|
||||
if grep -q "DB_PASSWORD=" .env.local; then
|
||||
grep "DB_PASSWORD=" .env.local | cut -d'=' -f2 > "$SECRETS_DIR/db_user_password.txt"
|
||||
chmod 600 "$SECRETS_DIR/db_user_password.txt"
|
||||
echo "? Created secrets/db_user_password.txt"
|
||||
sed -i '/^DB_PASSWORD=/d' .env.local
|
||||
fi
|
||||
|
||||
# APP_KEY
|
||||
if grep -q "APP_KEY=" .env.local; then
|
||||
grep "APP_KEY=" .env.local | cut -d'=' -f2 > "$SECRETS_DIR/app_key.txt"
|
||||
chmod 600 "$SECRETS_DIR/app_key.txt"
|
||||
echo "? Created secrets/app_key.txt"
|
||||
sed -i '/^APP_KEY=/d' .env.local
|
||||
fi
|
||||
|
||||
echo "? Migration completed. Please review .env.local and remove migrated secrets."
|
||||
```
|
||||
|
||||
#### 4.2 .env.local bereinigen
|
||||
- Entferne: `REDIS_PASSWORD=`, `DB_PASSWORD=`, `APP_KEY=`
|
||||
- Behalte: Alle anderen Konfigurationen (DB_HOST, DB_PORT, etc.)
|
||||
|
||||
### Phase 5: Dokumentation
|
||||
|
||||
#### 5.1 ENV_SETUP.md aktualisieren
|
||||
- Lokales Setup mit Secrets dokumentieren
|
||||
- Migration-Anleitung hinzuf?gen
|
||||
- Beispiel-Secrets erw?hnen
|
||||
|
||||
#### 5.2 README.md aktualisieren
|
||||
- Setup-Schritte f?r neue Entwickler
|
||||
- Secrets-Verzeichnis erstellen
|
||||
- Beispiel-Secrets kopieren
|
||||
|
||||
#### 5.3 .env.example aktualisieren
|
||||
- Kommentare zu `*_FILE` Pattern hinzuf?gen
|
||||
- Hinweis auf Secrets-Verzeichnis
|
||||
|
||||
## Detaillierte ?nderungen
|
||||
|
||||
### Datei: docker-compose.local.yml
|
||||
|
||||
```yaml
|
||||
services:
|
||||
php:
|
||||
environment:
|
||||
# Use Docker Secrets via *_FILE pattern (Framework supports this automatically)
|
||||
- DB_PASSWORD_FILE=/run/secrets/db_user_password
|
||||
- REDIS_PASSWORD_FILE=/run/secrets/redis_password
|
||||
- APP_KEY_FILE=/run/secrets/app_key
|
||||
secrets:
|
||||
- db_user_password
|
||||
- redis_password
|
||||
- app_key
|
||||
|
||||
redis:
|
||||
secrets:
|
||||
- redis_password
|
||||
command: >
|
||||
sh -c "redis-server
|
||||
--requirepass $$(cat /run/secrets/redis_password)
|
||||
--maxmemory 256mb
|
||||
--maxmemory-policy allkeys-lru
|
||||
--save 900 1
|
||||
--save 300 10
|
||||
--save 60 10000
|
||||
--appendonly yes
|
||||
--appendfsync everysec"
|
||||
healthcheck:
|
||||
test: ["CMD", "sh", "-c", "redis-cli --no-auth-warning -a $$(cat /run/secrets/redis_password) ping"]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
retries: 3
|
||||
start_period: 10s
|
||||
|
||||
queue-worker:
|
||||
environment:
|
||||
- DB_PASSWORD_FILE=/run/secrets/db_user_password
|
||||
- REDIS_PASSWORD_FILE=/run/secrets/redis_password
|
||||
secrets:
|
||||
- db_user_password
|
||||
- redis_password
|
||||
|
||||
secrets:
|
||||
db_user_password:
|
||||
file: ./secrets/db_user_password.txt
|
||||
external: false
|
||||
redis_password:
|
||||
file: ./secrets/redis_password.txt
|
||||
external: false
|
||||
app_key:
|
||||
file: ./secrets/app_key.txt
|
||||
external: false
|
||||
```
|
||||
|
||||
### Datei: docker-compose.base.yml
|
||||
|
||||
**Secrets-Sektion bereits vorhanden** (Zeilen 192-224), muss nur genutzt werden.
|
||||
|
||||
### Datei: docker/redis/redis.conf
|
||||
|
||||
**Anpassen oder entfernen:**
|
||||
```ini
|
||||
# docker/redis/redis.conf
|
||||
# Hinweis: Passwort wird via Docker Secrets geladen
|
||||
# requirepass wird nicht hier gesetzt, sondern via Command-Line-Args
|
||||
# In docker-compose.local.yml wird --requirepass verwendet
|
||||
```
|
||||
|
||||
## Migration f?r bestehende Entwickler
|
||||
|
||||
### Schritt-f?r-Schritt Anleitung
|
||||
|
||||
```bash
|
||||
# 1. Secrets-Verzeichnis erstellen
|
||||
mkdir -p secrets
|
||||
chmod 700 secrets
|
||||
|
||||
# 2. Secrets aus .env.local extrahieren
|
||||
# Redis Password
|
||||
REDIS_PASS=$(grep "^REDIS_PASSWORD=" .env.local | cut -d'=' -f2)
|
||||
if [ -n "$REDIS_PASS" ]; then
|
||||
echo "$REDIS_PASS" > secrets/redis_password.txt
|
||||
chmod 600 secrets/redis_password.txt
|
||||
echo "? Created secrets/redis_password.txt"
|
||||
fi
|
||||
|
||||
# DB Password
|
||||
DB_PASS=$(grep "^DB_PASSWORD=" .env.local | cut -d'=' -f2)
|
||||
if [ -n "$DB_PASS" ]; then
|
||||
echo "$DB_PASS" > secrets/db_user_password.txt
|
||||
chmod 600 secrets/db_user_password.txt
|
||||
echo "? Created secrets/db_user_password.txt"
|
||||
fi
|
||||
|
||||
# APP_KEY
|
||||
APP_KEY=$(grep "^APP_KEY=" .env.local | cut -d'=' -f2)
|
||||
if [ -n "$APP_KEY" ]; then
|
||||
echo "$APP_KEY" > secrets/app_key.txt
|
||||
chmod 600 secrets/app_key.txt
|
||||
echo "? Created secrets/app_key.txt"
|
||||
fi
|
||||
|
||||
# 3. Entferne Secrets aus .env.local (oder kommentiere aus)
|
||||
sed -i '/^REDIS_PASSWORD=/d' .env.local
|
||||
sed -i '/^DB_PASSWORD=/d' .env.local
|
||||
sed -i '/^APP_KEY=/d' .env.local
|
||||
|
||||
# 4. Pr?fe Secrets
|
||||
ls -la secrets/
|
||||
# Sollte zeigen: redis_password.txt, db_user_password.txt, app_key.txt
|
||||
|
||||
# 5. Teste Konfiguration
|
||||
docker compose -f docker-compose.base.yml -f docker-compose.local.yml config
|
||||
|
||||
# 6. Starte Container
|
||||
docker compose -f docker-compose.base.yml -f docker-compose.local.yml up -d
|
||||
|
||||
# 7. Teste Redis-Verbindung
|
||||
docker compose exec redis redis-cli --no-auth-warning -a $(cat secrets/redis_password.txt) ping
|
||||
# Erwartet: PONG
|
||||
```
|
||||
|
||||
## Setup f?r neue Entwickler
|
||||
|
||||
### Initial Setup Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# scripts/setup-local-secrets.sh
|
||||
|
||||
echo "?? Setting up local development secrets..."
|
||||
|
||||
SECRETS_DIR="./secrets"
|
||||
mkdir -p "$SECRETS_DIR"
|
||||
chmod 700 "$SECRETS_DIR"
|
||||
|
||||
# Generate Redis Password
|
||||
if [ ! -f "$SECRETS_DIR/redis_password.txt" ]; then
|
||||
REDIS_PASS=$(openssl rand -base64 32)
|
||||
echo "$REDIS_PASS" > "$SECRETS_DIR/redis_password.txt"
|
||||
chmod 600 "$SECRETS_DIR/redis_password.txt"
|
||||
echo "? Generated secrets/redis_password.txt"
|
||||
fi
|
||||
|
||||
# Generate DB Password
|
||||
if [ ! -f "$SECRETS_DIR/db_user_password.txt" ]; then
|
||||
DB_PASS=$(openssl rand -base64 32)
|
||||
echo "$DB_PASS" > "$SECRETS_DIR/db_user_password.txt"
|
||||
chmod 600 "$SECRETS_DIR/db_user_password.txt"
|
||||
echo "? Generated secrets/db_user_password.txt"
|
||||
echo "?? Update DB_PASSWORD in .env.local if needed"
|
||||
fi
|
||||
|
||||
# Generate APP_KEY (if not exists)
|
||||
if [ ! -f "$SECRETS_DIR/app_key.txt" ]; then
|
||||
APP_KEY=$(php -r "echo 'base64:' . base64_encode(random_bytes(32));")
|
||||
echo "$APP_KEY" > "$SECRETS_DIR/app_key.txt"
|
||||
chmod 600 "$SECRETS_DIR/app_key.txt"
|
||||
echo "? Generated secrets/app_key.txt"
|
||||
fi
|
||||
|
||||
echo "? Local secrets setup completed!"
|
||||
echo ""
|
||||
echo "?? Next steps:"
|
||||
echo "1. Review secrets/*.txt files"
|
||||
echo "2. Update .env.local if needed (DB_USERNAME, DB_HOST, etc.)"
|
||||
echo "3. Start containers: docker compose -f docker-compose.base.yml -f docker-compose.local.yml up -d"
|
||||
```
|
||||
|
||||
## Vorteile dieser L?sung
|
||||
|
||||
### 1. Konsistenz
|
||||
- ? Gleiche Konfiguration in Local, Staging, Production
|
||||
- ? Framework nutzt `DockerSecretsResolver` ?berall
|
||||
- ? Keine Environment-spezifischen Code-Pfade
|
||||
|
||||
### 2. Sicherheit
|
||||
- ? Secrets nicht in `.env.local` (kann versehentlich committed werden)
|
||||
- ? Dateisystem-Permissions (600) f?r Secrets
|
||||
- ? `.gitignore` verhindert versehentliches Committen
|
||||
|
||||
### 3. Wartbarkeit
|
||||
- ? Einheitliche Konfiguration
|
||||
- ? Framework unterst?tzt `*_FILE` Pattern automatisch
|
||||
- ? Klare Trennung: Secrets vs. Konfiguration
|
||||
|
||||
### 4. Entwickler-Erfahrung
|
||||
- ? Testen mit Production-?hnlicher Konfiguration
|
||||
- ? Fr?hes Erkennen von Secrets-Problemen
|
||||
- ? Setup-Script f?r neue Entwickler
|
||||
|
||||
## Nachteile / ?berlegungen
|
||||
|
||||
### 1. Komplexit?t
|
||||
- ?? **Mehr Setup-Schritte** f?r neue Entwickler
|
||||
- ?? **Zus?tzliche Secrets-Dateien** m?ssen verwaltet werden
|
||||
- ?? **Lokale Secrets-Verwaltung** n?tig
|
||||
|
||||
**L?sung**: Setup-Script automatisiert die Erstellung
|
||||
|
||||
### 2. Migration
|
||||
- ?? **Bestehende `.env.local`** muss angepasst werden
|
||||
- ?? **Secrets-Verzeichnis** muss erstellt werden
|
||||
- ?? **Dokumentation** muss aktualisiert werden
|
||||
|
||||
**L?sung**: Migration-Script unterst?tzt den ?bergang
|
||||
|
||||
### 3. Redis-Passwort lokal
|
||||
- ?? **Mehr Konfiguration** f?r lokale Entwicklung
|
||||
- ?? **Passwort muss bekannt sein** f?r Redis-CLI-Zugriff
|
||||
|
||||
**L?sung**:
|
||||
- Passwort in `secrets/redis_password.txt` (leicht zug?nglich lokal)
|
||||
- Helper-Script: `scripts/redis-cli.sh` f?r einfachen Zugriff
|
||||
|
||||
## Alternative Ans?tze
|
||||
|
||||
### Option A: Secrets optional machen (nicht empfohlen)
|
||||
- Redis-Passwort nur wenn Secret vorhanden
|
||||
- Komplexer, weniger konsistent
|
||||
|
||||
### Option B: Nur Production/Staging mit Secrets (aktuell)
|
||||
- Lokal bleibt ohne Secrets
|
||||
- **Nachteil**: Inkonsistenz zwischen Umgebungen
|
||||
|
||||
### Option C: Vereinheitlichung (empfohlen)
|
||||
- Alle Umgebungen nutzen Secrets
|
||||
- **Vorteil**: Maximale Konsistenz
|
||||
|
||||
## Empfehlung
|
||||
|
||||
**Vereinheitlichung (Option C)** ist die beste L?sung, weil:
|
||||
1. ? **Maximale Konsistenz** zwischen allen Umgebungen
|
||||
2. ? **Framework unterst?tzt bereits** `DockerSecretsResolver`
|
||||
3. ? **Bessere Sicherheit** auch lokal
|
||||
4. ? **Fr?hes Erkennen** von Secrets-Problemen
|
||||
5. ? **Setup-Script** macht Migration einfach
|
||||
|
||||
## N?chste Schritte
|
||||
|
||||
1. ? Plan erstellt
|
||||
2. ? Diskussion: Ist Vereinheitlichung gew?nscht?
|
||||
3. ? Implementierung: docker-compose.local.yml anpassen
|
||||
4. ? Migration: Secrets aus .env.local extrahieren
|
||||
5. ? Dokumentation: ENV_SETUP.md und README.md aktualisieren
|
||||
6. ? Testing: Lokale Entwicklungsumgebung testen
|
||||
7. ? Setup-Script: scripts/setup-local-secrets.sh erstellen
|
||||
359
docs/deployment/local-stack-restructure-plan.md
Normal file
359
docs/deployment/local-stack-restructure-plan.md
Normal file
@@ -0,0 +1,359 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user