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)
```bash
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)
```bash
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)

```bash
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

```bash
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

```bash
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](./initial-deployment-guide.md)

---

## 🔧 Manuelle Deployment-Operationen

### Code deployen (Git-basiert)

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

```bash
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-deployment-workflow.md)

### Code deployen (Manuell via SSH)

Falls ein manuelles Deployment nötig ist:

**Staging:**
```bash
# 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:**
```bash
# 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

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

### Infrastructure Setup (einmalig)

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

### Quick-Start Scripts

Für schnelle Tests und Verifikationen:

**Staging**:
```bash
cd ~/deployment
./scripts/staging-quick-start.sh
```

**Production**:
```bash
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**:
```bash
cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/verify-staging.yml
```

**Production**:
```bash
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)

```bash
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
  ```bash
  # 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

```bash
# 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](../../README.md)** - Haupt-Dokumentation
- **[quick-start.md](quick-start.md)** - Schnellstart-Guide
- **[code-change-workflow.md](code-change-workflow.md)** - Codeänderungen workflow

---

## 💡 Tipps

### Vault Passwort setzen

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

### Nur bestimmte Tasks ausführen

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

### Check Mode (Dry Run)

```bash
ansible-playbook ... --check --diff
```

### Inventory prüfen

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

### PHP Version anpassen

```bash
# 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 .
```