michaelschiemer/deployment/docs/guides/initial-deployment-guide.md

Initial Deployment Guide

Stand: 2025-11-07
Status: Vollständige Anleitung für erstes Deployment

---

Übersicht

Dieser Guide führt durch das komplette Initial Deployment des Application Stacks. Dieser Prozess wird einmalig beim ersten Setup durchgeführt. Für spätere Deployments siehe Code Deployment Workflow.

📖 Verwandte Dokumentation:

• Code Deployment Workflow - Unterschiede zwischen Initial und normalem Deployment
• Troubleshooting Guide - Häufige Probleme und Lösungen
• Application Stack Deployment - Detaillierter Deployment-Ablauf

---

Voraussetzungen

Bevor das Initial Deployment startet, müssen folgende Voraussetzungen erfüllt sein:

1. Infrastructure Stacks deployed

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/setup-infrastructure.yml \
  --vault-password-file secrets/.vault_pass \
  --skip-tags application

Wichtig: --skip-tags application überspringt den Application Stack, da dieser separat deployed wird.

2. Docker Image gebaut und gepusht

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/build-initial-image.yml \
  --vault-password-file secrets/.vault_pass

Was passiert:

• docker/entrypoint.sh wird auf LF Line Endings konvertiert (CRLF → LF)
• Docker Image wird gebaut (Dockerfile.production)
• Image wird zur Registry gepusht (localhost:5000/framework:latest)

3. Secrets konfiguriert

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/setup-production-secrets.yml \
  --vault-password-file secrets/.vault_pass

Erforderliche Secrets im Vault:

• vault_db_user_password - PostgreSQL Passwort
• vault_redis_password - Redis Passwort
• vault_app_key - Application Encryption Key
• vault_vault_encryption_key - Vault Encryption Key

---

Initial Deployment Workflow

Schritt 1: Application Code synchronisieren

Methode: Rsync-basiertes Sync vom lokalen Repository zum Server

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/sync-application-code.yml \
  --vault-password-file secrets/.vault_pass

Was passiert:

• Zielverzeichnis wird erstellt: /home/deploy/michaelschiemer/current
• Alte Dateien werden gelöscht (.git wird erhalten falls vorhanden)
• Code wird via rsync synchronisiert
• Excludes: vendor, node_modules, .env, deployment, docker, docs, tests
• Executable Permissions werden auf worker.php und console.php gesetzt
• Verifikation: Prüft ob worker.php, console.php, composer.json existieren

Wichtig: vendor wird nicht synchronisiert, da Dependencies im Container installiert werden.

Schritt 2: Composer Dependencies installieren

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/install-composer-dependencies.yml \
  --vault-password-file secrets/.vault_pass

Was passiert:

• composer install --no-dev --optimize-autoloader wird im php Container ausgeführt
• vendor/autoload.php wird erstellt
• queue-worker und scheduler werden neu gestartet (um vendor zu erkennen)

Voraussetzung: php Container muss bereits laufen (wird durch setup-infrastructure.yml gestartet).

Schritt 3: Application Stack deployen

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/setup-infrastructure.yml \
  --vault-password-file secrets/.vault_pass \
  --tags application

Was passiert:

• Docker Compose Stack wird deployed
• Secrets werden erstellt
• .env Datei wird generiert
• Container werden gestartet: php, web, queue-worker, scheduler
• Health Checks werden durchgeführt

Container-Konfiguration:

• php: Läuft PHP-FPM und Nginx (via entrypoint.sh)
• web: Nginx Reverse Proxy
• queue-worker: PHP CLI Worker (ohne entrypoint, direkter php worker.php Aufruf)
• scheduler: PHP CLI Scheduler (ohne entrypoint, direkter php console.php scheduler:run Aufruf)

---

Verifikation

Container Status prüfen

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/check-final-status.yml \
  --vault-password-file secrets/.vault_pass

Erwartetes Ergebnis:

NAME                          STATUS
production-php-1             Up X minutes (healthy)
production-web-1              Up X minutes (healthy)
production-queue-worker-1     Up X minutes
scheduler                     Up X minutes

Manuelle Verifikation

# SSH zum Server
ssh deploy@94.16.110.151

# Container Status
cd ~/deployment/stacks/production
docker compose -f docker-compose.base.yml -f docker-compose.production.yml ps

# Logs prüfen
docker compose -f docker-compose.base.yml -f docker-compose.production.yml logs web
docker compose -f docker-compose.base.yml -f docker-compose.production.yml logs queue-worker
docker compose -f docker-compose.base.yml -f docker-compose.production.yml logs scheduler

# Health Check
curl -k https://localhost/health

---

Häufige Probleme

Problem: Container starten nicht / sind unhealthy

Lösung: Siehe Troubleshooting Guide

Häufige Ursachen:

• Missing Secret Files → setup-production-secrets.yml ausführen
• Missing Application Code → sync-application-code.yml ausführen
• Missing vendor/autoload.php → install-composer-dependencies.yml ausführen
• PHP-FPM Permission Errors → fix-web-container.yml ausführen
• Environment Variables fehlen → recreate-containers-with-env.yml ausführen

Problem: Entrypoint Script "no such file or directory"

Ursache: CRLF Line Endings im docker/entrypoint.sh

Lösung:

• .gitattributes sollte *.sh text eol=lf enthalten
• build-initial-image.yml konvertiert automatisch zu LF

Problem: worker.php oder console.php fehlen

Ursache: Code wurde nicht synchronisiert

Lösung: sync-application-code.yml erneut ausführen

---

Unterschiede: Initial vs. Normal Deployment

Initial Deployment (dieser Guide)

• Code-Sync: Rsync vom lokalen Repository
• Verwendung: Einmalig beim ersten Setup
• Playbook: sync-application-code.yml

Normal Deployment (CI/CD)

• Code-Sync: Git Clone/Pull auf dem Server
• Verwendung: Regelmäßige Deployments via CI/CD
• Playbook: deploy-application-code.yml

Siehe auch: Code Deployment Workflow

---

Nächste Schritte

Nach erfolgreichem Initial Deployment:

1. CI/CD Pipeline konfigurieren

   • Gitea Actions Workflow einrichten
   • deploy-application-code.yml für zukünftige Deployments verwenden

2. Monitoring einrichten

   • Health Checks verifizieren
   • Logs überwachen
   • Alerts konfigurieren

3. Backup-Strategie

   • Database Backups einrichten
   • Application Data Backups konfigurieren

---

Referenz

• Application Stack Deployment - Detaillierter Ablauf
• Troubleshooting Guide - Probleme und Lösungen
• Code Deployment Workflow - Normal Deployment Workflow
• Deployment Commands - Command-Referenz