michaelschiemer/deployment/docs/guides/deployment-commands.md

Deployment Commands - Quick Reference

🚀 Automatisches Deployment (Empfohlen)

Standard-Workflow: Staging → Production

Empfohlener Workflow für sichere Deployments:

1. Push auf staging Branch (Standard für Entwicklung)

git add .
git commit -m "feat: Add new feature"
git push origin staging  # → Automatisches Deployment zu Staging

2. Testen auf Staging

• Staging URL: https://staging.michaelschiemer.de
• Tests durchführen und verifizieren

3. Merge nach main (nur nach erfolgreichem Test)

git checkout main
git merge staging
git push origin main  # → Automatisches Deployment zu Production

Was passiert automatisch:

Bei Push auf staging Branch:

• ✅ Tests werden ausgeführt
• ✅ Docker Image wird gebaut
• ✅ Image wird zur Registry gepusht
• ✅ Deployment auf Staging Server via SSH/SCP
• ✅ Staging Stack wird aktualisiert

Bei Push auf main Branch:

• ✅ Tests werden ausgeführt
• ✅ Docker Image wird gebaut
• ✅ Image wird zur Registry gepusht
• ✅ Deployment auf Production Server via SSH/SCP
• ✅ Production Stack wird aktualisiert

Pipeline Status: https://git.michaelschiemer.de/michael/michaelschiemer/actions

Wichtig:

• ⚠️ Niemals direkt auf main pushen - immer erst auf staging testen
• ✅ Staging ist der Standard-Branch für alle Entwicklungsarbeit
• ✅ Production-Deployment erfolgt nur nach erfolgreichem Test auf Staging

---

🔧 Initial Deployment (Einmalig)

Schritt 1: Code synchronisieren (Rsync)

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

Was passiert:

• Code wird vom lokalen Repository zum Server synchronisiert
• Ziel: /home/deploy/michaelschiemer/current
• Excludes: vendor, node_modules, .env, deployment, docker, docs, tests

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 im PHP Container
• queue-worker und scheduler werden neu gestartet

Schritt 3: Application Stack deployen

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

Siehe auch: Initial Deployment Guide

---

🔧 Manuelle Deployment-Operationen

Code deployen (Git-basiert)

Für zukünftige Deployments (nach Initial Setup):

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/deploy-application-code.yml \
  -e "git_branch=main" \
  --vault-password-file secrets/.vault_pass

Was passiert:

• Git Repository wird auf Server aktualisiert (git pull)
• Branch kann spezifiziert werden
• Executable Permissions werden gesetzt

Siehe auch: Code Deployment Workflow

Code deployen (Manuell via SSH)

Falls ein manuelles Deployment nötig ist:

Staging:

# Auf Staging Server
ssh deploy@94.16.110.151

# 1. PostgreSQL Staging Stack (falls noch nicht laufend)
cd ~/deployment/stacks/postgresql-staging
docker compose up -d

# 2. Staging Application Stack
cd ~/deployment/stacks/staging

# Docker Registry Login
echo "$REGISTRY_PASSWORD" | docker login registry.michaelschiemer.de \
  -u "$REGISTRY_USER" --password-stdin

# Image pullen
docker pull registry.michaelschiemer.de/framework:git-abc1234

# Stack aktualisieren
docker compose -f docker-compose.base.yml -f docker-compose.staging.yml up -d

Hinweis: Staging verwendet eine separate PostgreSQL-Datenbank (postgres-staging) im postgresql-staging Stack.

Production:

# Auf Production Server
ssh deploy@94.16.110.151

# 1. PostgreSQL Production Stack (falls noch nicht laufend)
cd ~/deployment/stacks/postgresql-production
docker compose up -d

# 2. Production Application Stack
cd ~/deployment/stacks/production

# Docker Registry Login
echo "$REGISTRY_PASSWORD" | docker login registry.michaelschiemer.de \
  -u "$REGISTRY_USER" --password-stdin

# Image pullen
docker pull registry.michaelschiemer.de/framework:git-abc1234

# Stack aktualisieren
docker compose -f docker-compose.base.yml -f docker-compose.production.yml up -d

Hinweis: Production verwendet eine separate PostgreSQL-Datenbank (postgres-production) im postgresql-production Stack.

Rollback zu vorheriger Version

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/rollback.yml

Infrastructure Setup (einmalig)

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/setup-infrastructure.yml

Quick-Start Scripts

Für schnelle Tests und Verifikationen:

Staging:

cd ~/deployment
./scripts/staging-quick-start.sh

Production:

cd ~/deployment
./scripts/production-quick-start.sh

Die Scripts bieten ein interaktives Menü für:

• PostgreSQL-Stacks starten
• Networks verifizieren
• Container-Status prüfen
• Datenbank-Verbindungen testen
• Health-Checks durchführen
• Logs anzeigen

Siehe auch: deployment/scripts/README.md

Verifikation mit Ansible (Empfohlen für CI/CD)

Staging:

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/verify-staging.yml

Production:

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/verify-production.yml

Die Ansible-Playbooks bieten:

• Idempotente Verifikationen
• Strukturierte Ausgabe
• CI/CD-Integration möglich
• Automatische Fehlerbehandlung

Vergleich Bash vs. Ansible: Siehe deployment/docs/guides/ansible-vs-bash-scripts.md

System Maintenance (regelmäßig)

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/system-maintenance.yml

---

📋 Verfügbare Ansible Playbooks

Infrastructure Setup

• playbooks/setup-infrastructure.yml - Deployed alle Stacks (Traefik, PostgreSQL, Registry, Gitea, Monitoring, Production)
• playbooks/setup-production-secrets.yml - Deployed Secrets zu Production
• playbooks/setup-ssl-certificates.yml - SSL Certificate Setup
• playbooks/sync-stacks.yml - Synchronisiert Stack-Konfigurationen

Troubleshooting & Maintenance

• playbooks/rollback.yml - Rollback zu vorheriger Version
• playbooks/troubleshoot.yml - Unified Troubleshooting Playbook mit Tags

  # Nur Diagnose
  ansible-playbook ... troubleshoot.yml --tags diagnose
  
  # Health Check prüfen
  ansible-playbook ... troubleshoot.yml --tags health,check
  
  # Health Checks fixen
  ansible-playbook ... troubleshoot.yml --tags health,fix
  
  # Nginx 404 fixen
  ansible-playbook ... troubleshoot.yml --tags nginx,404,fix
  
  # Alles ausführen
  ansible-playbook ... troubleshoot.yml --tags all
  

• playbooks/system-maintenance.yml - Führt Paket-Updates, Unattended-Upgrades und optional Docker-Pruning aus

VPN

• playbooks/setup-wireguard.yml - WireGuard VPN Setup
• playbooks/add-wireguard-client.yml - WireGuard Client hinzufügen

CI/CD

• playbooks/setup-gitea-runner-ci.yml - Gitea Runner CI Setup

---

🔧 Ansible Variablen

Häufig verwendete Extra Variables

# Image Tag für Deployment
-e "image_tag=abc1234-1696234567"

# Git Branch für Code Sync
-e "git_branch=main"
-e "git_repo_url=https://git.michaelschiemer.de/michael/michaelschiemer.git"

# Registry Credentials (wenn nicht im Vault)
-e "docker_registry_username=admin"
-e "docker_registry_password=secret"

# Dry Run (Check Mode)
--check

# Verbose Output
-v  # oder -vv, -vvv für mehr Details

---

📖 Vollständige Dokumentation

• README.md - Haupt-Dokumentation
• quick-start.md - Schnellstart-Guide
• code-change-workflow.md - Codeänderungen workflow

---

💡 Tipps

Vault Passwort setzen

export ANSIBLE_VAULT_PASSWORD_FILE=~/.ansible/vault_pass
# oder
ansible-playbook ... --vault-password-file ~/.ansible/vault_pass

Nur bestimmte Tasks ausführen

ansible-playbook ... --tags "deploy,restart"

Check Mode (Dry Run)

ansible-playbook ... --check --diff

Inventory prüfen

ansible -i inventory/production.yml production -m ping

PHP Version anpassen

# 1. Workflow-Variable aktualisieren (.gitea/workflows/production-deploy.yml)
PHP_VERSION=8.5.0RC4

# 2. Optionale lokale Builds (alle Dockerfiles akzeptieren PHP_VERSION):
docker build --build-arg PHP_VERSION=8.5.0RC4 -f docker/php/Dockerfile .
docker build --build-arg PHP_VERSION=8.5.0RC4 -f docker/ci/Dockerfile .
docker build --build-arg PHP_VERSION=8.5.0RC4 -f docker/worker/Dockerfile .