michaelschiemer/deployment/MIGRATION.md

Migration Guide: Legacy System → Two-Layer Deployment

Diese Anleitung beschreibt die Migration vom alten Deployment-System zum neuen Two-Layer Deployment-System.

Übersicht

Das neue System trennt klar zwischen:

• Infrastruktur-Layer: Traefik, Gitea, PostgreSQL (läuft dauerhaft)
• Application-Layer: PHP-App mit Nginx, Redis, Queue Workers (wird häufig deployt)

Voraussetzungen

• Backup aller Daten (PostgreSQL, Gitea, Volumes)
• SSH-Zugriff auf Production-Server
• Docker und Docker Compose installiert
• Ausreichend Disk-Space für Migration

Schritt 1: Backup erstellen

PostgreSQL Backup

# Auf dem Server
cd ~/deployment/legacy/stacks/postgresql-production
docker compose exec postgres pg_dump -U postgres michaelschiemer_production > /tmp/postgres_backup_$(date +%Y%m%d_%H%M%S).sql

# Staging-Datenbank (falls vorhanden)
docker compose exec postgres pg_dump -U postgres michaelschiemer_staging > /tmp/postgres_staging_backup_$(date +%Y%m%d_%H%M%S).sql

Gitea Backup

# Gitea-Daten Volume sichern
docker run --rm -v gitea-data:/data -v $(pwd):/backup alpine tar czf /backup/gitea_backup_$(date +%Y%m%d_%H%M%S).tar.gz /data

Application Volumes Backup

# Production-Code Volume
docker run --rm -v production-code:/data -v $(pwd):/backup alpine tar czf /backup/production_code_backup_$(date +%Y%m%d_%H%M%S).tar.gz /data

# Production-Storage Volume
docker run --rm -v production-storage:/data -v $(pwd):/backup alpine tar czf /backup/production_storage_backup_$(date +%Y%m%d_%H%M%S).tar.gz /data

Schritt 2: Infrastruktur deployen

2.1 Verzeichnisstruktur erstellen

# Auf dem Server
mkdir -p /home/deploy/infrastructure/{traefik,gitea,postgresql}/secrets

2.2 Secrets erstellen

# Traefik ACME E-Mail
echo "your-email@example.com" > /home/deploy/infrastructure/traefik/secrets/acme_email.txt
chmod 600 /home/deploy/infrastructure/traefik/secrets/acme_email.txt

# Gitea PostgreSQL Passwort
openssl rand -base64 32 > /home/deploy/infrastructure/gitea/secrets/postgres_password.txt
chmod 600 /home/deploy/infrastructure/gitea/secrets/postgres_password.txt

# Gitea Redis Passwort
openssl rand -base64 32 > /home/deploy/infrastructure/gitea/secrets/redis_password.txt
chmod 600 /home/deploy/infrastructure/gitea/secrets/redis_password.txt

# Application PostgreSQL Passwort (aus altem System übernehmen oder neu generieren)
# Altes Passwort aus Legacy-System extrahieren oder neu generieren:
openssl rand -base64 32 > /home/deploy/infrastructure/postgresql/secrets/postgres_password.txt
chmod 600 /home/deploy/infrastructure/postgresql/secrets/postgres_password.txt

2.3 Infrastructure Stacks deployen

Reihenfolge ist wichtig:

# 1. Traefik (muss zuerst laufen)
cd /home/deploy/infrastructure/traefik
docker compose up -d

# Warten bis Traefik läuft
sleep 10
docker compose ps

# 2. PostgreSQL (wird von Application benötigt)
cd /home/deploy/infrastructure/postgresql
docker compose up -d

# Warten bis PostgreSQL läuft
sleep 10
docker compose ps

# 3. Gitea (nutzt Traefik für SSL)
cd /home/deploy/infrastructure/gitea
docker compose up -d

# Warten bis Gitea läuft
sleep 10
docker compose ps

2.4 Verifikation

# Traefik Dashboard
curl -k https://traefik.michaelschiemer.de

# PostgreSQL erreichbar
docker network inspect app-internal

# Gitea erreichbar
curl -k https://git.michaelschiemer.de

Schritt 3: Daten migrieren

3.1 PostgreSQL-Daten migrieren

# Neue Datenbanken erstellen (falls nicht vorhanden)
docker compose exec -T postgres psql -U postgres << EOF
CREATE DATABASE michaelschiemer;
CREATE DATABASE michaelschiemer_staging;
EOF

# Production-Datenbank wiederherstellen
docker compose exec -T postgres psql -U postgres michaelschiemer < /tmp/postgres_backup_*.sql

# Staging-Datenbank wiederherstellen (falls vorhanden)
docker compose exec -T postgres psql -U postgres michaelschiemer_staging < /tmp/postgres_staging_backup_*.sql

3.2 Gitea-Daten migrieren

# Altes Gitea stoppen
cd ~/deployment/legacy/stacks/gitea
docker compose down

# Gitea-Daten Volume kopieren
docker run --rm \
  -v gitea-data:/source:ro \
  -v gitea-data-new:/dest \
  alpine sh -c "cp -a /source/. /dest/"

# Neues Gitea starten (nutzt gitea-data Volume)
cd /home/deploy/infrastructure/gitea
docker compose up -d

Schritt 4: Application deployen

4.1 Application-Code auf Server deployen

# Auf dem Server
mkdir -p /home/deploy/michaelschiemer/current
cd /home/deploy/michaelschiemer/current

# Code klonen (oder von altem System kopieren)
git clone https://git.michaelschiemer.de/michael/michaelschiemer.git .

# Oder: Code von altem System kopieren
# cp -r ~/deployment/legacy/stacks/production/current/* .

4.2 Secrets konfigurieren

# Secrets-Verzeichnis erstellen
mkdir -p deployment/secrets/{staging,production}

# Production Secrets (aus altem System übernehmen oder neu generieren)
openssl rand -base64 32 > deployment/secrets/production/db_password.txt
openssl rand -base64 32 > deployment/secrets/production/redis_password.txt
openssl rand -base64 32 > deployment/secrets/production/app_key.txt
chmod 600 deployment/secrets/production/*.txt

# Staging Secrets
openssl rand -base64 32 > deployment/secrets/staging/db_password.txt
openssl rand -base64 32 > deployment/secrets/staging/redis_password.txt
openssl rand -base64 32 > deployment/secrets/staging/app_key.txt
chmod 600 deployment/secrets/staging/*.txt

Wichtig: Passwörter müssen mit denen in der PostgreSQL-Infrastruktur übereinstimmen!

4.3 Application deployen

# Production deployen
./deployment/scripts/deploy.sh production

# Oder Staging deployen
./deployment/scripts/deploy.sh staging

Schritt 5: Altes System stoppen

Nur nach erfolgreicher Migration!

# Alte Stacks stoppen
cd ~/deployment/legacy/stacks/production
docker compose down

cd ~/deployment/legacy/stacks/staging
docker compose down

# Alte Networks prüfen (können gelöscht werden, wenn nicht mehr benötigt)
docker network ls

Schritt 6: Verifikation

6.1 Application erreichbar

# Production
curl -I https://michaelschiemer.de

# Staging
curl -I https://staging.michaelschiemer.de

6.2 Database-Verbindung testen

# Von Application-Container aus
docker compose exec php php console.php db:status

6.3 Health Checks

# Application Health Endpoint
curl https://michaelschiemer.de/health

# Container-Status
docker compose ps

Rollback-Plan

Falls Migration fehlschlägt:

1. Altes System wieder starten:

   cd ~/deployment/legacy/stacks/production
   docker compose up -d
   

2. Daten aus Backup wiederherstellen:

   # PostgreSQL
   docker compose exec -T postgres psql -U postgres michaelschiemer < /tmp/postgres_backup_*.sql
   

3. Probleme analysieren:

   • Logs prüfen: docker compose logs
   • Network-Verbindungen prüfen: docker network inspect
   • Secrets prüfen

4. Anpassungen vornehmen und erneut migrieren

Checkliste

• Backup aller Daten erstellt
• Infrastruktur-Stacks deployt (Traefik, PostgreSQL, Gitea)
• Networks korrekt konfiguriert
• Secrets erstellt und konfiguriert
• PostgreSQL-Daten migriert
• Gitea-Daten migriert
• Application deployt
• Health Checks erfolgreich
• Application erreichbar
• Database-Verbindung funktioniert
• Altes System gestoppt (nach Verifikation)

Troubleshooting

Network-Probleme

# Networks prüfen
docker network ls
docker network inspect traefik-public
docker network inspect app-internal
docker network inspect infrastructure

Secrets-Probleme

# Secrets-Dateien prüfen
ls -la deployment/secrets/production/
ls -la deployment/infrastructure/*/secrets/

# Berechtigungen prüfen
stat deployment/secrets/production/db_password.txt

Container startet nicht

# Logs prüfen
docker compose logs -f <service-name>

# Container-Status
docker compose ps

# Network-Verbindungen
docker network inspect <network-name>

Support

Bei Problemen während der Migration:

1. Logs sammeln: docker compose logs > migration_logs.txt
2. Container-Status: docker compose ps > container_status.txt
3. Network-Status: docker network ls > network_status.txt