michaelschiemer/deployment/docs/guides/code-deployment-workflow.md

Code Deployment Workflow

Stand: 2025-11-07
Status: Vollständige Dokumentation der Code-Deployment-Methoden

---

Übersicht

Dieses Dokument erklärt die beiden verfügbaren Methoden für Code-Deployment:

1. Rsync-basiert - Für Initial Deployment
2. Git-basiert - Für CI/CD und zukünftige Deployments

📖 Verwandte Dokumentation:

• Initial Deployment Guide - Schritt-für-Schritt Initial Deployment
• Deployment Commands - Command-Referenz
• Application Stack Deployment - Detaillierter Ablauf

---

Deployment-Methoden im Vergleich

Methode 1: Rsync-basiert (sync-application-code.yml)

Verwendung: Initial Deployment (einmalig)

Vorteile:

• ✅ Funktioniert ohne Git Repository auf Server
• ✅ Schnell für einmaliges Setup
• ✅ Exakte Kontrolle über synchronisierte Dateien
• ✅ Funktioniert auch wenn Git nicht verfügbar ist

Nachteile:

• ❌ Erfordert lokales Repository
• ❌ Nicht für CI/CD geeignet
• ❌ Manueller Prozess

Playbook: deployment/ansible/playbooks/sync-application-code.yml

Was wird synchronisiert:

• Alle PHP-Dateien
• Konfigurationsdateien
• Assets (wenn nicht excluded)

Was wird NICHT synchronisiert:

• vendor (wird im Container installiert)
• node_modules
• .env Dateien
• deployment/, docker/, docs/, tests/

---

Methode 2: Git-basiert (deploy-application-code.yml)

Verwendung: CI/CD und zukünftige Deployments

Vorteile:

• ✅ Automatisierbar via CI/CD
• ✅ Version Control Integration
• ✅ Git Commit History verfügbar
• ✅ Branch-basierte Deployments möglich
• ✅ Rollback einfach (Git Checkout)

Nachteile:

• ❌ Erfordert Git Repository auf Server
• ❌ Erfordert Git Credentials (Token/SSH Key)

Playbook: deployment/ansible/playbooks/deploy-application-code.yml

Was passiert:

• Git Repository wird geklont (falls nicht vorhanden)
• Repository wird aktualisiert (git pull)
• Branch kann spezifiziert werden
• Executable Permissions werden gesetzt

---

Workflow-Diagramme

Initial Deployment (Rsync)

Local Repository
    ↓
rsync (via Ansible)
    ↓
Server: /home/deploy/michaelschiemer/current
    ↓
Docker Volume Mount
    ↓
Container: /var/www/html

Normal Deployment (Git)

Git Repository (Gitea)
    ↓
Git Clone/Pull (via Ansible)
    ↓
Server: /home/deploy/michaelschiemer/current
    ↓
Docker Volume Mount
    ↓
Container: /var/www/html

CI/CD Deployment (Git)

Developer → git push
    ↓
Gitea Actions Trigger
    ↓
Build Docker Image
    ↓
Push to Registry
    ↓
Ansible: deploy-application-code.yml
    ↓
Git Pull auf Server
    ↓
Docker Compose Restart

---

Wann welche Methode verwenden?

Initial Deployment → Rsync

Verwendung:

• ✅ Erstes Setup des Servers
• ✅ Server hat noch kein Git Repository
• ✅ Lokales Repository ist verfügbar
• ✅ Manuelles Deployment gewünscht

Beispiel:

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

Normal Deployment → Git

Verwendung:

• ✅ CI/CD Pipeline
• ✅ Regelmäßige Deployments
• ✅ Branch-basierte Deployments (staging, production)
• ✅ Automatisierung gewünscht

Beispiel:

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

---

Detaillierte Workflows

Initial Deployment Workflow (Rsync)

Schritt 1: Code synchronisieren

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

Schritt 2: Composer Dependencies installieren

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

Schritt 3: Application Stack deployen

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

Siehe auch: Initial Deployment Guide

---

Normal Deployment Workflow (Git)

Schritt 1: Code deployen

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

Schritt 2: Composer Dependencies aktualisieren (falls nötig)

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

Schritt 3: Container neu starten (falls nötig)

# Auf Server
cd ~/deployment/stacks/production
docker compose -f docker-compose.base.yml -f docker-compose.production.yml restart

---

CI/CD Deployment Workflow (Git)

Automatisch via Gitea Actions:

1. Developer pusht Code:

   git push origin main
   

2. Gitea Actions Pipeline:

   • Tests ausführen
   • Docker Image bauen
   • Image zur Registry pushen
   • Ansible Playbook ausführen

3. Ansible Playbook (deploy-application-code.yml):

   • Git Repository auf Server aktualisieren
   • Composer Dependencies installieren (falls composer.json geändert)
   • Container neu starten

Siehe auch: Application Stack Deployment

---

Best Practices

Code-Synchronisation

1. Immer vendor ausschließen

   • Dependencies werden im Container installiert
   • Verhindert Platform-spezifische Probleme

2. .env niemals synchronisieren

   • Environment-spezifische Konfiguration
   • Wird von Ansible generiert

3. Executable Permissions setzen

   • worker.php und console.php müssen ausführbar sein
   • Playbooks setzen automatisch 0755

Git-Deployment

1. Branch-spezifische Deployments

   # Staging
   -e "git_branch=staging"
   
   # Production
   -e "git_branch=main"
   

2. Git Credentials

   • SSH Keys für private Repositories
   • Git Tokens für HTTPS
   • Credentials werden via Ansible Vault verwaltet

3. Rollback

   # Auf Server
   cd /home/deploy/michaelschiemer/current
   git checkout <previous-commit-hash>
   docker compose restart
   

---

Troubleshooting

Problem: Rsync synchronisiert nicht alle Dateien

Lösung: Excludes in sync-application-code.yml prüfen

Problem: Git Pull schlägt fehl

Ursachen:

• Git Credentials fehlen
• Repository existiert nicht
• Branch existiert nicht

Lösung: Siehe Troubleshooting Guide

Problem: Code-Änderungen werden nicht erkannt

Lösung: Container neu starten

docker compose -f docker-compose.base.yml -f docker-compose.production.yml restart

---

Migration: Rsync → Git

Nach Initial Deployment kann auf Git-Deployment umgestellt werden:

Schritt 1: Git Repository auf Server initialisieren

# Auf Server
cd /home/deploy/michaelschiemer/current
git init
git remote add origin https://git.michaelschiemer.de/michael/michaelschiemer.git
git fetch
git checkout main

Schritt 2: Zukünftige Deployments via Git

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

---

Referenz

• Initial Deployment Guide - Initial Deployment Anleitung
• Deployment Commands - Command-Referenz
• Application Stack Deployment - Detaillierter Ablauf
• Troubleshooting Guide - Probleme und Lösungen