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](./initial-deployment-guide.md) - Schritt-für-Schritt Initial Deployment
- [Deployment Commands](./deployment-commands.md) - Command-Referenz
- [Application Stack Deployment](../reference/application-stack.md) - 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:**
```bash
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:**
```bash
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**
```bash
ansible-playbook -i inventory/production.yml \
  playbooks/sync-application-code.yml \
  --vault-password-file secrets/.vault_pass
```

**Schritt 2: Composer Dependencies installieren**
```bash
ansible-playbook -i inventory/production.yml \
  playbooks/install-composer-dependencies.yml \
  --vault-password-file secrets/.vault_pass
```

**Schritt 3: Application Stack deployen**
```bash
ansible-playbook -i inventory/production.yml \
  playbooks/setup-infrastructure.yml \
  --tags application \
  --vault-password-file secrets/.vault_pass
```

**Siehe auch:** [Initial Deployment Guide](./initial-deployment-guide.md)

---

### Normal Deployment Workflow (Git)

**Schritt 1: Code deployen**
```bash
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)**
```bash
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)**
```bash
# 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:**
   ```bash
   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](../reference/application-stack.md)

---

## 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**
   ```bash
   # 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**
   ```bash
   # 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](../troubleshooting/initial-deployment-issues.md)

### Problem: Code-Änderungen werden nicht erkannt

**Lösung:** Container neu starten
```bash
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**
```bash
# 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**
```bash
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-guide.md) - Initial Deployment Anleitung
- [Deployment Commands](./deployment-commands.md) - Command-Referenz
- [Application Stack Deployment](../reference/application-stack.md) - Detaillierter Ablauf
- [Troubleshooting Guide](../troubleshooting/initial-deployment-issues.md) - Probleme und Lösungen