michael/michaelschiemer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: sync staging workspace

Browse Source
This commit is contained in:
Michael Schiemer
2025-11-01 19:02:09 +01:00
parent 478754ab02
commit 5a79646daf
58 changed files with 2035 additions and 709 deletions
Download Patch File Download Diff File Expand all files Collapse all files

198
deployment/docs/README.md Normal file
View File

@@ -0,0 +1,198 @@
# Deployment Dokumentation - Index
**Stand:** 2025-11-01
**Status:** ? Vollst?ndige Dokumentation vorhanden
---
## ?? Schnellstart
### F?r schnellen Einstieg
1. **[quick-start.md](guides/quick-start.md)** ?
- Schnellstart-Guide
- Pipeline-Status pr?fen
- Troubleshooting Quick Reference
2. **[code-change-workflow.md](guides/code-change-workflow.md)**
- Wie Code?nderungen gepusht werden
- Automatisches vs. manuelles Deployment
- Branching-Strategien
- Beispiel-Workflows
---
## ?? Detaillierte Guides
### Setup & Konfiguration
3. **[setup-guide.md](guides/setup-guide.md)**
- Kompletter Setup-Guide von Anfang bis Ende
- Infrastructure Deployment
- Gitea Runner Setup
- Secrets Konfiguration
- Schritt-f?r-Schritt Anleitung
4. **[deployment-commands.md](guides/deployment-commands.md)**
- Command-Referenz f?r Deployment
- Ansible Playbook Befehle
- Docker Compose Kommandos
- Troubleshooting Kommandos
5. **[vault-password.md](guides/vault-password.md)**
- Ansible Vault Password Dokumentation
- Setup und Verwaltung
- CI/CD Integration
- Best Practices
### Deployment-Prozess
6. **[application-stack.md](reference/application-stack.md)**
- Detaillierter Deployment-Ablauf Schritt f?r Schritt
- Was passiert bei jedem Deployment
- Container-Neustart Details
- Rollback-Prozess
- Troubleshooting
---
## ?? Status & ?bersicht
### Projekt-Status
7. **[deployment-summary.md](status/deployment-summary.md)**
- Was ist fertig?
- Was fehlt noch?
- Completion Rate
- N?chste Schritte
8. **[deployment-todo.md](status/deployment-todo.md)**
- Aktuelle TODO-Liste
- Priorisierte Reihenfolge
- Quick Checklist
### CI/CD Pipeline
9. **[ci-cd-status.md](status/ci-cd-status.md)**
- Aktueller CI/CD Status
- Secrets-?bersicht
- Runner-Status
- Checkliste f?r Completion
- Troubleshooting
### Verbesserungen & Planung
10. **[improvements.md](status/improvements.md)**
- Verbesserungsvorschl?ge
- Refactoring-Ideen
- Architektur-?berlegungen
11. **[next-steps.md](status/next-steps.md)**
- Geplante n?chste Schritte
- Roadmap
- Priorit?ten
---
## ?? Stack-spezifische Dokumentation
### Infrastructure Stacks
- **[stacks/traefik/README.md](../stacks/traefik/README.md)** - Reverse Proxy & SSL
- **[stacks/postgresql/README.md](../stacks/postgresql/README.md)** - Database mit Backups
- **[stacks/registry/README.md](../stacks/registry/README.md)** - Private Docker Registry
- **[stacks/gitea/README.md](../stacks/gitea/README.md)** - Git Server & CI/CD
- **[stacks/monitoring/README.md](../stacks/monitoring/README.md)** - Monitoring Tools
### Application Stack
- **[stacks/application/README.md](../stacks/application/README.md)** - Application Stack Details
- **[ansible/README.md](../ansible/README.md)** - Ansible Playbooks Dokumentation
### CI/CD
- **[gitea-runner/README.md](../gitea-runner/README.md)** - Gitea Runner Setup
- **[.gitea/workflows/production-deploy.yml](../../.gitea/workflows/production-deploy.yml)** - Haupt-Deployment-Pipeline
---
## ?? Security & VPN
- **[vault-password.md](guides/vault-password.md)** - Ansible Vault Password Dokumentation
- **[docs/WIREGUARD-SETUP.md](../../docs/WIREGUARD-SETUP.md)** - WireGuard VPN Setup
- **[ansible/playbooks/README-WIREGUARD.md](../ansible/playbooks/README-WIREGUARD.md)** - WireGuard Ansible Playbooks
---
## ?? Troubleshooting
### Workflow-Probleme
- **[workflow-troubleshooting.md](reference/workflow-troubleshooting.md)** - Workflow Troubleshooting
- **[quick-start.md](guides/quick-start.md)** - Troubleshooting Quick Reference
### Test-Dokumentation
- **[test-results.md](tests/test-results.md)** - Test Ergebnisse
- **[git-deployment-test.md](tests/git-deployment-test.md)** - Git Deployment Tests
- **[git-deployment-issue.md](tests/git-deployment-issue.md)** - Git Deployment Issues
- **[test-git-deployment.md](tests/test-git-deployment.md)** - Git Deployment Test Guide
- **[quick-test.md](tests/quick-test.md)** - Quick Tests
- **[recommended-test-flow.md](tests/recommended-test-flow.md)** - Empfohlene Test-Workflows
---
## ?? Historie & Logs
- **[cleanup-log.md](history/cleanup-log.md)** - Cleanup Log
- **[cleanup-summary.md](history/cleanup-summary.md)** - Cleanup Zusammenfassung
---
## ?? Haupt-Dokumentation
- **[README.md](../README.md)** - Haupt-Dokumentation & Architektur-?bersicht
---
## ?? Empfohlene Lesereihenfolge
### F?r neue Nutzer
1. **[quick-start.md](guides/quick-start.md)** - Schneller ?berblick
2. **[code-change-workflow.md](guides/code-change-workflow.md)** - Code deployen lernen
3. **[deployment-summary.md](status/deployment-summary.md)** - Projekt-Status verstehen
### F?r Deployment-Verst?ndnis
1. **[application-stack.md](reference/application-stack.md)** - Wie Deployment funktioniert
2. **[ci-cd-status.md](status/ci-cd-status.md)** - CI/CD Pipeline verstehen
3. **[setup-guide.md](guides/setup-guide.md)** - Komplette Setup-Anleitung
### F?r Troubleshooting
1. **[quick-start.md](guides/quick-start.md)** - Quick Troubleshooting
2. **[workflow-troubleshooting.md](reference/workflow-troubleshooting.md)** - Workflow-Probleme
3. Stack-spezifische READMEs f?r Details
---
## ?? Dokumentations-Standards
**Alle Dokumentationsdateien:**
- Verwenden Markdown-Format
- Haben klare ?berschriften-Struktur
- Enthalten Code-Beispiele
- Haben Troubleshooting-Abschnitte (wenn relevant)
- Verlinken zu verwandten Dokumenten
**Standards:**
- ? Beispiele sind ausf?hrbar
- ? Pfade sind absolut oder relativ klar
- ? Screenshots/Links sind aktuell
- ? Status ist klar markiert (?/??/?)
---
**Letzte Aktualisierung:** 2025-11-01
**Status:** ? Dokumentation vollst?ndig

223
deployment/docs/RESTRUCTURE_PROPOSAL.md Normal file
View File

@@ -0,0 +1,223 @@
# Dokumentations-Restrukturierung - Vorschlag
## Aktuelle Situation
### Statistiken
- **Gesamt:** 34 Markdown-Dateien im `deployment/` Ordner
- **Root-Level:** 21 Markdown-Dateien direkt in `deployment/`
- **Verlinkungen:** 35 Referenzen im `DOCUMENTATION_INDEX.md`
### Problem
- Viele Dokumentationsdateien direkt im Root (`deployment/*.md`)
- Mischung aus:
- Haupt-Dokumentation (README.md, SETUP-GUIDE.md)
- Status/Tracking (DEPLOYMENT_SUMMARY.md, DEPLOYMENT-TODO.md)
- Test/Entwicklung (TEST_*.md, GIT_*.md, QUICK_TEST.md)
- Troubleshooting (WORKFLOW-TROUBLESHOOTING.md, CI_CD_STATUS.md)
- Logs/Historie (CLEANUP_LOG.md, CLEANUP_SUMMARY.md)
- Schwer ?berschaubar
- Konfigurationsdateien (ansible/, stacks/, gitea-runner/) vermischt mit Docs
## Vorschlag: Strukturierte Dokumentation
### Neue Struktur
```
deployment/
??? README.md # ? Haupt-Dokumentation (bleibt)
??? docs/ # ?? Alle Dokumentation
? ??? README.md # Dokumentations-Index (ersetzt DOCUMENTATION_INDEX.md)
? ?
? ??? guides/ # ?? Anleitungen & Guides
? ? ??? setup-guide.md # (SETUP-GUIDE.md)
? ? ??? quick-start.md # (QUICK_START.md)
? ? ??? code-change-workflow.md # (CODE_CHANGE_WORKFLOW.md)
? ? ??? deployment-commands.md # (DEPLOYMENT_COMMANDS.md)
? ? ??? vault-password.md # (ansible/VAULT_PASSWORD.md)
? ?
? ??? reference/ # ?? Referenz-Dokumentation
? ? ??? application-stack.md # (APPLICATION_STACK_DEPLOYMENT.md)
? ? ??? ansible-playbooks.md # (ansible/README.md)
? ? ??? workflow-troubleshooting.md # (WORKFLOW-TROUBLESHOOTING.md)
? ?
? ??? status/ # ?? Status & Tracking
? ? ??? deployment-summary.md # (DEPLOYMENT_SUMMARY.md)
? ? ??? deployment-todo.md # (DEPLOYMENT-TODO.md)
? ? ??? ci-cd-status.md # (CI_CD_STATUS.md)
? ? ??? improvements.md # (IMPROVEMENTS.md)
? ? ??? next-steps.md # (NEXT_STEPS.md)
? ?
? ??? testing/ # ?? Test-Dokumentation
? ? ??? test-results.md # (TEST_RESULT.md)
? ? ??? git-deployment-test.md # (GIT_DEPLOYMENT_TEST.md)
? ? ??? git-deployment-issue.md # (GIT_DEPLOYMENT_ISSUE.md)
? ? ??? test-git-deployment.md # (TEST_GIT_DEPLOYMENT.md)
? ? ??? quick-test.md # (QUICK_TEST.md)
? ? ??? recommended-test-flow.md # (RECOMMENDED_TEST_FLOW.md)
? ?
? ??? history/ # ?? Logs & Historie
? ??? cleanup-log.md # (CLEANUP_LOG.md)
? ??? cleanup-summary.md # (CLEANUP_SUMMARY.md)
?
??? ansible/ # Ansible Konfiguration
? ??? README.md # ? Kurze ?bersicht, Link zu docs/reference/
? ??? ...
?
??? stacks/ # Docker Compose Stacks
? ??? */README.md # Stack-spezifische Docs (bleiben)
?
??? gitea-runner/ # Runner Konfiguration
??? README.md # Runner-spezifische Docs (bleibt)
```
## Vorteile
### ? ?bersichtlichkeit
- Klare Trennung: Docs vs. Konfiguration
- Kategorisierung nach Zweck (Guides, Reference, Status, Tests, History)
- Einfacher zu navigieren
### ? Wartbarkeit
- Logische Gruppierung ?hnlicher Dokumente
- Einfaches Finden relevanter Dokumentation
- Einfachere Aktualisierung
### ? Klare Hierarchie
- `docs/README.md` als zentraler Einstiegspunkt
- `deployment/README.md` bleibt f?r Architektur-?bersicht
- Stack-spezifische READMEs bleiben nahe am Code
### ? Saubere Struktur
- Konfigurationsdateien nicht mit Docs vermischt
- Tests getrennt von Produktions-Docs
- Historie/Logs in separatem Bereich
## Nachteile
### ?? Breaking Changes
- Alle Verlinkungen m?ssen aktualisiert werden
- Externe Referenzen (z.B. in anderen Projekten) m?ssen angepasst werden
- Git-Historie wird aufgeteilt
### ?? Migration-Aufwand
- 21 Dateien m?ssen verschoben werden
- Verlinkungen in vielen Dateien aktualisieren
- CI/CD Skripte k?nnten Pfade referenzieren
### ?? Gew?hnung
- Team muss neue Struktur lernen
- Neue Pfade m?ssen bekannt gemacht werden
## Alternative: Minimale Restrukturierung
Falls die vollst?ndige Restrukturierung zu aufw?ndig ist:
### Option B: Nur Root-Level aufr?umen
```
deployment/
??? README.md # Haupt-Dokumentation
??? DOCUMENTATION_INDEX.md # Index (bleibt)
?
??? docs/ # Nur Root-Level Docs verschieben
? ??? guides/
? ? ??? setup-guide.md
? ? ??? quick-start.md
? ? ??? code-change-workflow.md
? ?
? ??? status/
? ? ??? deployment-summary.md
? ? ??? deployment-todo.md
? ? ??? ci-cd-status.md
? ?
? ??? tests/ # Test-Dokumentation
? ??? test-results.md
? ??? ...
?
??? ansible/ # Bleibt wie es ist
? ??? README.md
?
??? stacks/ # Bleibt wie es ist
```
**Vorteile:**
- Weniger Breaking Changes
- Schneller umzusetzen
- Hauptproblem (Root-Level Unordnung) gel?st
**Nachteile:**
- Keine vollst?ndige Strukturierung
- Stack-Docs bleiben verstreut
## Empfehlung
### F?r jetzt: **Option B (Minimal)**
1. ? Schnell umsetzbar
2. ? L?sen des Hauptproblems (21 Root-Level Dateien)
3. ? Minimal invasive ?nderungen
4. ? Stack-Docs bleiben nahe am Code (gut!)
### Sp?ter: **Option A (Vollst?ndig)** wenn:
- Mehr Zeit f?r Migration vorhanden
- Automatisierung f?r Link-Updates verf?gbar
- Team w?chst und bessere Struktur ben?tigt
## Migration-Plan (Option B)
### Phase 1: Docs-Ordner erstellen
```bash
mkdir -p deployment/docs/{guides,status,tests}
```
### Phase 2: Dateien verschieben
```bash
# Guides
mv SETUP-GUIDE.md docs/guides/setup-guide.md
mv QUICK_START.md docs/guides/quick-start.md
mv CODE_CHANGE_WORKFLOW.md docs/guides/code-change-workflow.md
mv DEPLOYMENT_COMMANDS.md docs/guides/deployment-commands.md
mv ansible/VAULT_PASSWORD.md docs/guides/vault-password.md
# Status
mv DEPLOYMENT_SUMMARY.md docs/status/deployment-summary.md
mv DEPLOYMENT-TODO.md docs/status/deployment-todo.md
mv CI_CD_STATUS.md docs/status/ci-cd-status.md
mv IMPROVEMENTS.md docs/status/improvements.md
mv NEXT_STEPS.md docs/status/next-steps.md
# Tests
mv TEST_RESULT.md docs/tests/test-results.md
mv GIT_DEPLOYMENT_TEST.md docs/tests/git-deployment-test.md
mv GIT_DEPLOYMENT_ISSUE.md docs/tests/git-deployment-issue.md
mv TEST_GIT_DEPLOYMENT.md docs/tests/test-git-deployment.md
mv QUICK_TEST.md docs/tests/quick-test.md
mv RECOMMENDED_TEST_FLOW.md docs/tests/recommended-test-flow.md
# Reference (optional, kann auch bleiben)
mv APPLICATION_STACK_DEPLOYMENT.md docs/reference/application-stack.md
mv WORKFLOW-TROUBLESHOOTING.md docs/reference/workflow-troubleshooting.md
# History (optional)
mv CLEANUP_LOG.md docs/history/cleanup-log.md
mv CLEANUP_SUMMARY.md docs/history/cleanup-summary.md
```
### Phase 3: Verlinkungen aktualisieren
- `DOCUMENTATION_INDEX.md` aktualisieren
- `README.md` Verlinkungen pr?fen
- Interne Links in Dokumenten pr?fen
- CI/CD Skripte pr?fen
### Phase 4: README.md erstellen
- `docs/README.md` als neuen Index erstellen
- `DOCUMENTATION_INDEX.md` ? `docs/README.md` migrieren
## Entscheidung ben?tigt
**Frage:** Soll die Dokumentation restrukturiert werden?
- ? **Ja, Option B (Minimal)** - Nur Root-Level aufr?umen
- ? **Ja, Option A (Vollst?ndig)** - Komplette Restrukturierung
- ? **Nein** - Behalten wie es ist
**Empfehlung:** Option B f?r jetzt, Option A sp?ter wenn n?tig.

551
deployment/docs/guides/code-change-workflow.md Normal file
View File

@@ -0,0 +1,551 @@
# Codeänderungen pushen und deployen
## Übersicht
Dieses Dokument erklärt, wie Codeänderungen gepusht werden und automatisch in Production deployed werden.
**Quick Start:**
```bash
git add .
git commit -m "feat: Add new feature"
git push origin main
```
→ Automatisches Deployment startet (~8-15 Minuten)
**📖 Verwandte Dokumentation:**
- **[Application Stack Deployment](../reference/application-stack.md)** - Wie das Deployment genau funktioniert
- **[CI/CD Status](../status/ci-cd-status.md)** - Aktueller Status der Pipeline
---
## Normaler Workflow: Codeänderungen deployen
### Schritt 1: Code lokal ändern
```bash
# Änderungen in deinem lokalen Repository machen
# z.B. Datei bearbeiten: src/App/Controller/HomeController.php
# Änderungen anzeigen
git status
# Änderungen anschauen
git diff
```
### Schritt 2: Änderungen committen
```bash
# Änderungen zum Staging hinzufügen
git add .
# Oder nur spezifische Dateien
git add src/App/Controller/HomeController.php
# Commit erstellen
git commit -m "feat: Add new feature to home controller"
```
**Commit-Message Konventionen:**
- `feat:` - Neue Feature
- `fix:` - Bug-Fix
- `refactor:` - Code-Refactoring
- `docs:` - Dokumentation
- `test:` - Tests
- `chore:` - Wartungsaufgaben
### Schritt 3: Code zu Gitea pushen
```bash
# Zu main branch pushen (triggert automatisches Deployment)
git push origin main
# Oder zu anderem Branch pushen (kein Auto-Deploy)
git push origin feature/new-feature
```
### Schritt 4: Automatisches Deployment
**Was passiert automatisch:**
1. **Git Push** → Gitea erhält den Push
2. **Workflow wird getriggert** (bei Push zu `main` Branch)
3. **CI/CD Pipeline startet:**
- Tests laufen
- Docker Image wird gebaut
- Image wird zur Registry gepusht
- Ansible Deployment wird ausgeführt
- Application Stack wird aktualisiert
**Zeitdauer:** ~8-15 Minuten für komplettes Deployment
---
## Deployment-Trigger
### Automatisches Deployment (bei Push zu `main`)
**Workflow:** `.gitea/workflows/production-deploy.yml`
```yaml
on:
push:
branches:
- main
paths-ignore:
- 'docs/**'
- '**.md'
- '.github/**'
```
**Bedeutung:**
- ✅ Push zu `main` Branch → Deployment startet automatisch
- ❌ Push zu anderen Branches → Kein Deployment
- ❌ Push nur von Markdown-Dateien → Kein Deployment (wegen `paths-ignore`)
**Beispiel:**
```bash
# Triggert Deployment
git push origin main
# Triggert KEIN Deployment (nur Markdown)
git commit -m "docs: Update README" --only README.md
git push origin又问
# Triggert KEIN Deployment (anderer Branch)
git checkout -b feature/new-feature
git push origin feature/new-feature
```
### Manuelles Deployment (Workflow-Dispatch)
**Workflow kann manuell gestartet werden:**
1. Gehe zu: `https://git.michaelschiemer.de/michael/michaelschiemer/actions`
2. Wähle: "Production Deployment Pipeline"
3. Klicke: "Run workflow"
4. Wähle Branch (z.B. `main` oder anderer Branch)
5. Optionale Einstellungen:
- `skip_tests`: `true` (nur in Notfällen!)
6. Klicke: "Run workflow"
**Verwendung:**
- Deployment von anderem Branch (z.B. `develop`, `staging`)
- Deployment ohne Code-Änderung (z.B. nach Config-Änderung)
- Notfall-Deployment mit `skip_tests: true`
---
## Workflow-Details
### Was passiert bei jedem Push zu `main`?
#### Job 1: Tests (ca. 2-5 Minuten)
```yaml
- PHP 8.3 Setup
- Composer Dependencies installieren
- Pest Tests ausführen
- PHPStan Code Quality Check
- Code Style Check (composer cs)
```
**Bei Fehler:** Pipeline stoppt, kein Deployment
#### Job 2: Build (ca. 3-5 Minuten)
```yaml
- Docker Buildx Setup
- Image Metadata generieren (Tag: <short-sha>-<timestamp>)
- Docker Image Build (Dockerfile.production)
- Image mit Tags pushen:
- registry.michaelschiemer.de/framework:latest
- registry.michaelschiemer.de/framework:<tag>
- registry.michaelschiemer.de/framework:git-<short-sha>
```
#### Job 3: Deploy (ca. 2-4 Minuten)
```yaml
- SSH Setup (mit Secret)
- Ansible Installation
- Ansible Playbook ausführen:
- Image Pull
- docker-compose.yml Update
- Stack Neustart
- Health-Check (10x versuche)
- Rollback bei Fehler
```
---
## Branching-Strategie
### Empfohlener Workflow
```
main (Production)
↓
develop (Entwicklung/Testing)
↓
feature/* (Feature Branches)
```
### Workflow-Beispiele
#### 1. Feature entwickeln
```bash
# Feature Branch erstellen
git checkout -b feature/user-authentication
# Änderungen machen
# ... Code schreiben ...
# Committen
git add .
git commit -m "feat: Add user authentication"
# Zu Gitea pushen (kein Auto-Deploy)
git push origin feature/user-authentication
# Pull Request erstellen in Gitea
# → Code Review
# → Merge zu develop (oder main)
```
#### 2. Direkt zu Production deployen
```bash
# Änderungen lokal
git checkout main
# ... Änderungen machen ...
git add .
git commit -m "fix: Critical bug fix"
# Pushen → Triggert automatisches Deployment
git push origin main
# Pipeline läuft automatisch:
# ✅ Tests
# ✅ Build
# ✅ Deploy
```
#### 3. Hotfix (Notfall)
```bash
# Hotfix Branch von main
git checkout -b hotfix/critical-security-fix main
# Fix implementieren
# ... Code schreiben ...
git add .
git commit -m "fix: Critical security vulnerability"
# Direkt zu main mergen
git checkout main
git merge hotfix/critical-security-fix Ker
# Pushen → Auto-Deploy
git push origin main
# Optional: Manuelles Deployment mit skip_tests
# (nur wenn Tests lokal bereits erfolgreich)
```
---
## Deployment-Status prüfen
### 1. Pipeline-Status in Gitea
```
https://git.michaelschiemer.de/michael/michaelschiemer/actions
```
**Status-Anzeigen:**
- 🟢 Grüner Haken = Erfolgreich
- 🔴 Roter Haken = Fehlgeschlagen
- 🟡 Gelber Kreis = Läuft gerade
### 2. Logs ansehen
1. Gehe zu Actions
2. Klicke auf den Workflow-Run
3. Klicke auf Job (z.B. "Deploy to Production Server")
4. Klicke auf Step (z.B. "Deploy via Ansible")
5. Logs ansehen
### 3. Application-Status prüfen
```bash
# SSH zum Production-Server
ssh deploy@94.16.110.151
# Container-Status prüfen
cd ~/deployment/stacks/application
docker compose ps
# Logs ansehen
docker compose logs -f app
# Health-Check manuell
curl https://michaelschiemer.de/health
```
---
## Deployment verhindern
### Temporäres Deployment verhindern
**Option 1: Push zu anderem Branch**
```bash
# Entwickle auf Feature-Branch
git checkout -b feature/my-feature
git push origin feature/my-feature
# → Kein Auto-Deploy
```
**Option CT 2: [skip ci] in Commit-Message**
```bash
# Workflow wird übersprungen
git commit -m "docs: Update documentation [skip ci]"
git push origin main
```
**Hinweis:** `[skip ci]` wird aktuell **nicht** unterstützt, da kein entsprechender Filter im Workflow ist.
### Deployment-Trigger deaktivieren
**Temporär (Workflow anpassen):**
```yaml
# In .gitea/workflows/production-deploy.yml
on:
push:
branches:
- main
# workflow_dispatch: # Kommentiere aus für temporäres Deaktivieren
```
**Besser:** Nutze Feature-Branches für Entwicklung ohne Auto-Deploy.
---
## Häufige Szenarien
### Szenario 1: Kleine Bug-Fix
```bash
# 1. Bug-Fix lokal implementieren
git checkout main
# ... Fix implementieren ...
git add .
git commit -m "fix: Resolve login issue"
# 2. Pushen → Auto-Deploy
git push origin main
# 3. Pipeline beobachten
# → Tests ✅
# → Build ✅
# → Deploy ✅
# 4. Verifizieren
curl https://michaels chasing.de/health
```
### Szenario 2: Große Feature-Entwicklung
```bash
# 1. Feature-Branch erstellen
git checkout -b feature/new-dashboard
# 2. Feature entwickeln
# ... viele Commits ...
# 3. Regelmäßig pushen (kein Auto-Deploy)
git push origin feature/new-dashboard
# 4. Pull Request erstellen in Gitea
# → Code Review
# → Diskussion
# 5. Merge zu main (triggert Auto-Deploy)
# → Via Gitea UI: "Merge Pull Request"
# → Oder lokal:
git checkout main
git merge feature/new-dashboard
git push origin main
```
### Szenario 3: Config-Änderung ohne Code-Änderung
```bash
# Beispiel: .env Variablen ändern
# (wird über Ansible Template generiert, daher direkt auf Server ändern)
# Oder: docker-compose.yml anpassen
# Änderungen machen
git add .
git commit -m "chore: Update docker-compose configuration"
git push origin main
# → Pipeline läuft
# → Build: Keine Code-Änderung, aber Image wird neu getaggt
# → Deploy: docker-compose.yml wird aktualisiert
```
### Szenario 4: Notfall-Rollback
```bash
# Option 1: Rollback via Ansible Playbook
cd deployment/ansible
ansible-playbook -i inventory/production.yml \
playbooks/rollback.yml \
-e "rollback_timestamp=2025-10-31T01-20-15Z"
# Option 2: Alten Commit pushen
git log --oneline
# Finde letzten funktionierenden Commit
git checkout <commit-hash>
git checkout -b rollback/previous-version
git push origin rollback/previous-version
# Manuell zu main mergen oder direkt:
git checkout main
git reset --hard <commit-hash>
git push origin main --force # ⚠️ Vorsicht!
# → Triggert Auto-Deploy mit altem Code
```
---
## Best Practices
### 1. Commits
- ✅ Klare, beschreibende Commit-Messages
entweder
- ✅ Atomic Commits (ein Feature = ein Commit)
- ✅ Regelmäßig pushen (nicht alles auf einmal)
### 2. Testing
- ✅ Tests lokal ausführen vor Push:
```bash
composer cs # Code Style
make phpstan # Static Analysis
./vendor/bin/pest # Tests
```
### 3. Deployment
- ✅ **Niemals** direkt zu `main` pushen ohne lokale Tests
- ✅ Feature-Branches für größere Änderungen
- ✅ Pull Requests für Code Review
- ✅ Pipeline-Status beobachten nach Push
### 4. Rollback-Plan
- ✅ Immer Backup vor größeren Änderungen
- ✅ Rollback-Playbook bereit halten
- ✅ Deployment-Metadaten dokumentieren
---
## Troubleshooting
### Pipeline schlägt fehl
**Problem:** Tests fehlgeschlagen
```bash
# Tests lokal ausführen
./vendor/bin/pest
# Fehler beheben
# ... Code anpassen ...
git add .
git commit -m "fix: Fix failing tests"
git push origin main
```
**Problem:** Build fehlgeschlagen
```bash
# Docker Build lokal testen
docker build -f Dockerfile.production -t test-image .
# Fehler beheben
# ... Dockerfile anpassen ...
git add .
git commit -m "fix: Fix Docker build"
git push origin main
```
**Problem:** Deployment fehlgeschlagen
```bash
# SSH zum Server
ssh deploy@94.16.110.151
# Logs prüfen
cd ~/deployment/stacks/application
docker compose logs app
# Manuell rollback
cd ~/deployment/ansible
ansible-playbook -i inventory/production.yml playbooks/rollback.yml
```
### Deployment läuft zu lange
**Pipeline hängt:**
- Prüfe Runner-Status: `docker compose ps` in `deployment/gitea-runner`
- Prüfe Runner-Logs: `docker compose logs gitea-runner`
- Prüfe Workflow-Logs in Gitea UI
**Deployment hängt:**
- Prüfe Server-Status: `ssh deploy@94.16.110.151 "docker ps"`
- Prüfe Container-Logs: `docker compose logs`
- Prüfe Disk-Space: `df -h`
---
## Zusammenfassung
### Normaler Workflow
1. **Code ändern** lokal
2. **Committen** mit klarer Message
3. **Push zu `main`** → Auto-Deploy startet
4. **Pipeline beobachten** in Gitea Actions
5. **Verifizieren** auf Production
### Wichtige Commands
```bash
# Änderungen pushen (triggert Auto-Deploy)
git push origin main
# Feature entwickeln (kein Auto-Deploy)
git checkout -b feature/my-feature
git push origin feature/my-feature
# Pipeline-Status prüfen
# → https://git.michaelschiemer.de/michael/michaelschiemer/actions
# Application-Status prüfen
ssh deploy@94.16.110.151 "cd ~/deployment/stacks/application && docker compose ps"
```
### Deployment-Zeit
- **Gesamt:** ~8-15 Minuten
- **Tests:** ~2-5 Minuten
- **Build:** ~3-5 Minuten
- **Deploy:** ~2-4 Minuten
- **Health-Check:** ~1 Minute
---
**Ready to deploy!** 🚀

151
deployment/docs/guides/deployment-commands.md Normal file
View File

@@ -0,0 +1,151 @@
# Deployment Commands - Quick Reference
Alle Deployment-Operationen werden über **Ansible Playbooks** durchgeführt.
---
## 🚀 Häufig verwendete Commands
### Code deployen (Image-basiert)
```bash
cd deployment/ansible
ansible-playbook -i inventory/production.yml \
playbooks/deploy-update.yml \
-e "image_tag=abc1234-1696234567" \
-e "git_commit_sha=$(git rev-parse HEAD)"
```
### Code synchen (Git-basiert)
```bash
cd deployment/ansible
ansible-playbook -i inventory/production.yml \
playbooks/sync-code.yml \
-e "git_branch=main"
```
### 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
```
---
## 📋 Alle verfügbaren Playbooks
### Deployment & Updates
- **`playbooks/deploy-update.yml`** - Deployt neues Docker Image
- **`playbooks/sync-code.yml`** - Synchronisiert Code aus Git Repository
- **`playbooks/rollback.yml`** - Rollback zu vorheriger Version
### Infrastructure Setup
- **`playbooks/setup-infrastructure.yml`** - Deployed alle Stacks (Traefik, PostgreSQL, Registry, Gitea, Monitoring, Application)
- **`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/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
```
### 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
```

192
deployment/docs/guides/quick-start.md Normal file
View File

@@ -0,0 +1,192 @@
# Quick Start Guide - Deployment & CI/CD
## 🚀 Schnellstart: Code deployen
### Einfachste Methode
```bash
# 1. Code ändern
# ... Dateien bearbeiten ...
# 2. Committen
git add .
git commit -m "feat: Add new feature"
# 3. Pushen → Automatisches Deployment!
git push origin main
```
**Das war's!** Die Pipeline läuft automatisch (~8-15 Minuten).
---
## 📋 Status-Übersicht
### ✅ Vollständig konfiguriert
- ✅ **CI/CD Pipeline** - Automatisches Deployment bei Push zu `main`
- ✅ **Gitea Runner** - Läuft und ist registriert
- ✅ **Secrets** - Alle kritischen Secrets konfiguriert
- ✅ **Application Stack** - Integration in `setup-infrastructure.yml`
- ✅ **Ansible Playbooks** - Deployment & Rollback vorhanden
### ⚠️ Ausstehend
- [ ] **Pipeline testen** - End-to-End Test durchführen
- [ ] **Backup-Scripts** - Backup-Playbook erstellen
- [ ] **Dokumentation vervollständigen** - Finale Updates
---
## 🔍 Pipeline-Status prüfen
### Nach einem Push
**Gitea Actions UI:**
```
https://git.michaelschiemer.de/michael/michaelschiemer/actions
```
**Status-Anzeigen:**
- 🟢 Grüner Haken = Erfolgreich
- 🔴 Roter Haken = Fehlgeschlagen
- 🟡 Gelber Kreis = Läuft gerade
**Logs ansehen:**
1. Klicke auf den Workflow-Run
2. Klicke auf Job (z.B. "Deploy to Production Server")
3. Klicke auf Step (z.B. "Deploy via Ansible")
4. Logs ansehen
### Application-Status prüfen
```bash
# SSH zum Production-Server
ssh deploy@94.16.110.151
# Container-Status
cd ~/deployment/stacks/application
docker compose ps
# Logs ansehen
docker compose logs app
# Health-Check
curl https://michaelschiemer.de/health
```
---
## 📚 Vollständige Dokumentation
### Deployment-Dokumentation
- **`CODE_CHANGE_WORKFLOW.md`** - Wie Codeänderungen gepusht werden
- **`APPLICATION_STACK_DEPLOYMENT.md`** - Detaillierter Deployment-Ablauf
- **`CI_CD_STATUS.md`** - CI/CD Pipeline Status & Checkliste
- **`DEPLOYMENT-TODO.md`** - Aktuelle TODO-Liste
### Setup-Dokumentation
- **`docs/guides/setup-guide.md`** - Kompletter Setup-Guide
- **`ansible/README.md`** - Ansible Playbooks Dokumentation
- **`stacks/application/README.md`** - Application Stack Details
### Workflow-Dokumentation
- **`.gitea/workflows/production-deploy.yml`** - Haupt-Deployment-Pipeline
- **`.gitea/workflows/TEST_WORKFLOW.md`** - Workflow-Test-Anleitung
---
## 🎯 Nächste Schritte
### 1. Pipeline testen (Empfohlen)
**Option A: Test-Commit pushen**
```bash
# Kleine Änderung
echo "# Test" >> README.md
git add README.md
git commit -m "test: CI/CD pipeline test"
git push origin main
```
**Option B: Workflow manuell triggern**
```
https://git.michaelschiemer.de/michael/michaelschiemer/actions
→ "Production Deployment Pipeline"
→ "Run workflow"
```
### 2. Backup-Scripts erstellen
```bash
# Backup-Playbook erstellen
cd deployment/ansible/playbooks
# → Erstelle backup.yml
```
### 3. Dokumentation finalisieren
- Finale Updates in `DEPLOYMENT-STATUS.md`
- README aktualisieren
---
## 🆘 Troubleshooting
### Pipeline schlägt fehl
**Tests fehlgeschlagen:**
```bash
# Tests lokal ausführen
./vendor/bin/pest
composer cs
make phpstan
```
**Build fehlgeschlagen:**
```bash
# Docker Build lokal testen
docker build -f Dockerfile.production -t test .
```
**Deployment fehlgeschlagen:**
```bash
# Logs prüfen
ssh deploy@94.16.110.151 "cd ~/deployment/stacks/application && docker compose logs"
# Manueller Rollback
cd deployment/ansible
ansible-playbook -i inventory/production.yml playbooks/rollback.yml
```
### Runner-Probleme
```bash
# Runner-Status prüfen
cd deployment/gitea-runner
docker compose ps
docker compose logs gitea-runner
# Runner neu starten
docker compose restart gitea-runner
```
---
## 📞 Support
**Dokumentation:**
- `deployment/README.md` - Haupt-Dokumentation
- `deployment/CI_CD_STATUS.md` - CI/CD Details
- `deployment/CODE_CHANGE_WORKFLOW.md` - Workflow-Guide
**Gitea:**
- Actions: `https://git.michaelschiemer.de/michael/michaelschiemer/actions`
- Runners: `https://git.michaelschiemer.de/admin/actions/runners`
---
**Ready to deploy!** 🚀

793
deployment/docs/guides/setup-guide.md Normal file
View File

@@ -0,0 +1,793 @@
# Production Deployment - Complete Setup Guide
**Status**: 🚧 In Progress
**Last Updated**: 2025-10-30
**Target Server**: 94.16.110.151 (Netcup)
---
## Overview
This guide walks through the complete setup of production deployment from scratch, covering:
1. Gitea Runner (Development Machine)
2. Ansible Vault Secrets
3. Production Server Initial Setup
4. CI/CD Pipeline Testing
5. Monitoring & Health Checks
---
## Prerequisites
**Development Machine:**
- ✅ Docker & Docker Compose installed
- ✅ Ansible installed (`pip install ansible`)
- ✅ SSH key for production server (`~/.ssh/production`)
- ✅ Git SSH key configured (see Phase 0)
- ✅ Access to Gitea admin panel
**Production Server (94.16.110.151):**
- ✅ Docker & Docker Compose installed
- ✅ User `deploy` created with Docker permissions
- ✅ SSH access configured
- ✅ Firewall configured (ports 80, 443, 2222)
---
## Phase 0: Git Repository SSH Access Setup (Development Machine)
### Step 0.1: Generate Git SSH Key
Create a separate SSH key specifically for Git operations (different from the production server SSH key):
```bash
# Generate SSH key for Git
ssh-keygen -t ed25519 -f ~/.ssh/git_michaelschiemer -C "git@michaelschiemer.de" -N ""
# Set correct permissions
chmod 600 ~/.ssh/git_michaelschiemer
chmod 644 ~/.ssh/git_michaelschiemer.pub
```
### Step 0.2: Configure SSH Config
Add Git SSH configuration to `~/.ssh/config`:
```bash
# Edit SSH config
nano ~/.ssh/config
```
Add the following configuration:
```
Host git.michaelschiemer.de
HostName git.michaelschiemer.de
Port 2222
User git
IdentityFile ~/.ssh/git_michaelschiemer
StrictHostKeyChecking no
UserKnownHostsFile /dev/null
```
### Step 0.3: Add Public Key to Gitea
1. Display your public key:
```bash
cat ~/.ssh/git_michaelschiemer.pub
```
2. Copy the output (starts with `ssh-ed25519 ...`)
3. In Gitea:
- Go to **Settings** → **SSH / GPG Keys**
- Click **Add Key**
- Paste the public key
- Click **Add Key**
4. Verify the connection:
```bash
ssh -T git@git.michaelschiemer.de
```
Expected output: `Hi there! You've successfully authenticated...`
### Step 0.4: Update Git Remote (if needed)
If your `origin` remote uses HTTPS, switch it to SSH:
```bash
# Check current remote URL
git remote -v
# Update to SSH
git remote set-url origin git@git.michaelschiemer.de:michael/michaelschiemer.git
# Test push (should work without password prompt)
git push origin main
```
**Note**: This SSH key is separate from the production server SSH key (`~/.ssh/production`). The production key is used for Ansible/server access, while the Git key is only for repository operations.
---
## Phase 1: Gitea Runner Setup (Development Machine)
### Step 1.1: Get Gitea Registration Token
1. Navigate to Gitea admin panel:
```
https://git.michaelschiemer.de/admin/actions/runners
```
2. Click **"Create New Runner"**
3. Copy the registration token (format: `<long-random-string>`)
### Step 1.2: Configure Runner Environment
```bash
cd deployment/gitea-runner
# Copy environment template
cp .env.example .env
# Edit configuration
nano .env
```
**Required Configuration in `.env`:**
```bash
# Gitea Instance URL
GITEA_INSTANCE_URL=https://git.michaelschiemer.de
# Registration Token (from Step 1.1)
GITEA_RUNNER_REGISTRATION_TOKEN=<your-token-from-gitea>
# Runner Name (appears in Gitea UI)
GITEA_RUNNER_NAME=dev-runner-01
# Runner Labels (environments this runner supports)
GITEA_RUNNER_LABELS=ubuntu-latest:docker://node:20-bullseye,ubuntu-22.04:docker://catthehacker/ubuntu:act-22.04
# Runner Capacity (concurrent jobs)
GITEA_RUNNER_CAPACITY=1
# Docker-in-Docker settings
DOCKER_HOST=tcp://docker-dind:2376
DOCKER_TLS_VERIFY=1
```
### Step 1.3: Register and Start Runner
```bash
# Register runner with Gitea
./register.sh
# Expected output:
# ✅ Starting Gitea Runner services...
# ✅ Runner registered successfully
# ✅ Runner is now active
# Verify runner is running
docker compose ps
# Check logs
docker compose logs -f gitea-runner
```
### Step 1.4: Verify Runner in Gitea
1. Go to: https://git.michaelschiemer.de/admin/actions/runners
2. You should see `dev-runner-01` listed as **"Idle"** or **"Active"**
3. Status should be green/online
**✅ Checkpoint**: Runner visible in Gitea UI and showing as "Idle"
---
## Phase 2: Ansible Vault Secrets Setup
### Step 2.1: Create Vault Password
```bash
cd deployment/ansible/secrets
# Create vault password file (gitignored)
echo "your-secure-vault-password-here" > .vault_pass
# Secure the file
chmod 600 .vault_pass
```
**⚠️ IMPORTANT**: Store this vault password in your password manager! You'll need it for all Ansible operations.
### Step 2.2: Create Production Secrets File
```bash
# Copy example template
cp production.vault.yml.example production.vault.yml
# Edit with your actual secrets
nano production.vault.yml
```
**Required Secrets in `production.vault.yml`:**
```yaml
---
# Docker Registry Credentials
docker_registry_user: "admin"
docker_registry_password: "your-registry-password"
# Application Environment Variables
app_key: "base64:generated-32-character-key"
app_env: "production"
app_debug: "false"
# Database Credentials
db_host: "postgres"
db_port: "5432"
db_name: "framework_production"
db_user: "framework_user"
db_password: "your-secure-db-password"
# Redis Configuration
redis_host: "redis"
redis_port: "6379"
redis_password: "your-secure-redis-password"
# Cache Configuration
cache_driver: "redis"
cache_prefix: "framework"
# Queue Configuration
queue_connection: "redis"
queue_name: "default"
# Session Configuration
session_driver: "redis"
session_lifetime: "120"
# Encryption Keys
encryption_key: "base64:your-32-byte-encryption-key"
state_encryption_key: "base64:your-32-byte-state-encryption-key"
# SMTP Configuration (Optional)
mail_mailer: "smtp"
mail_host: "smtp.example.com"
mail_port: "587"
mail_username: "noreply@michaelschiemer.de"
mail_password: "your-smtp-password"
mail_encryption: "tls"
mail_from_address: "noreply@michaelschiemer.de"
mail_from_name: "Framework"
# Admin IPs (comma-separated)
admin_allowed_ips: "127.0.0.1,::1"
# Rate Limiting
rate_limit_enabled: "true"
rate_limit_default: "60"
rate_limit_window: "60"
```
### Step 2.3: Generate Encryption Keys
```bash
# Generate app_key (32 bytes base64)
php -r "echo 'base64:' . base64_encode(random_bytes(32)) . PHP_EOL;"
# Generate encryption_key (32 bytes base64)
php -r "echo 'base64:' . base64_encode(random_bytes(32)) . PHP_EOL;"
# Generate state_encryption_key (32 bytes base64)
php -r "echo 'base64:' . base64_encode(random_bytes(32)) . PHP_EOL;"
# Copy these values into production.vault.yml
```
### Step 2.4: Encrypt Secrets File
```bash
# Encrypt the secrets file
ansible-vault encrypt production.vault.yml \
--vault-password-file .vault_pass
# Verify encryption worked
file production.vault.yml
# Should output: production.vault.yml: ASCII text
# View encrypted content (should show encrypted data)
cat production.vault.yml
# Test decryption (view content)
ansible-vault view production.vault.yml \
--vault-password-file .vault_pass
```
**✅ Checkpoint**: `production.vault.yml` is encrypted and can be decrypted with vault password
---
## Phase 3: Production Server Initial Setup
### Prerequisites
Before running Phase 3, ensure:
- ✅ SSH access to production server configured (`~/.ssh/production`)
- ✅ Repository cloned on production server at `~/deployment/stacks` (or adjust `stacks_base_path` in playbook)
- ✅ Ansible installed on your development machine: `pip install ansible`
- ✅ Ansible collections installed: `ansible-galaxy collection install community.docker`
### Step 3.1: Clone Repository on Production Server (if not already done)
**On Production Server:**
```bash
# SSH to production server
ssh deploy@94.16.110.151
# Clone repository (if not already present)
mkdir -p ~/deployment
cd ~/deployment
git clone git@git.michaelschiemer.de:michael/michaelschiemer.git . || git clone https://git.michaelschiemer.de/michael/michaelschiemer.git .
```
### Step 3.2: Deploy Infrastructure Stacks with Ansible
**On Development Machine:**
```bash
# Navigate to Ansible directory
cd deployment/ansible
# Run infrastructure deployment playbook
ansible-playbook playbooks/setup-infrastructure.yml \
-i inventory/production.yml
# The playbook will:
# 1. Create required Docker networks (traefik-public, app-internal)
# 2. Deploy Traefik (Reverse Proxy & SSL)
# 3. Deploy PostgreSQL (Database)
# 4. Deploy Docker Registry (Private Registry)
# 5. Deploy Gitea (Git Server + PostgreSQL)
# 6. Deploy Monitoring (Portainer + Grafana + Prometheus)
# 7. Wait for all services to be healthy
# 8. Verify accessibility
```
**Expected output:**
- ✅ All stacks deployed successfully
- ✅ All services healthy
- ✅ Gitea accessible at https://git.michaelschiemer.de
**Note:** If monitoring passwords need to be stored in Vault (recommended for production), add them to `secrets/production.vault.yml`:
- `vault_grafana_admin_password`
- `vault_prometheus_password`
Then run the playbook with vault:
```bash
ansible-playbook playbooks/setup-infrastructure.yml \
-i inventory/production.yml \
--vault-password-file secrets/.vault_pass
```
### Step 3.3: Configure Gitea (Manual Step)
1. Access Gitea: https://git.michaelschiemer.de
2. Complete initial setup wizard (first-time only):
- **Database Type**: PostgreSQL
- **Database Host**: `postgres:5432`
- **Database User**: `gitea`
- **Database Password**: `gitea_password` (or check `deployment/stacks/gitea/docker-compose.yml`)
- **Database Name**: `gitea`
- **Admin Account**: Create your admin user
- **Repository Root**: `/data/git/repositories` (default)
3. **Enable Actions** (required for Phase 1):
- Go to **Site Administration** → **Actions**
- Enable **Enable Actions** checkbox
- Save settings
### Step 3.4: Verify Docker Registry
The Ansible playbook automatically creates registry authentication. To retrieve credentials:
```bash
# SSH to production server
ssh deploy@94.16.110.151
# View registry htpasswd (contains username:password hash)
cat ~/deployment/stacks/registry/auth/htpasswd
# The default username is 'admin'
# Password hash can be used to login, or create new user:
cd ~/deployment/stacks/registry
docker compose exec registry htpasswd -Bbn <username> <password> >> auth/htpasswd
docker compose restart registry
# Test login
docker login registry.michaelschiemer.de
# Or if using port:
docker login registry.michaelschiemer.de
```
**✅ Checkpoint**: All infrastructure stacks running, Gitea accessible, Actions enabled
---
## Phase 4: Deploy Application Secrets
### Step 4.1: Deploy Secrets to Production
**On Development Machine:**
```bash
cd deployment/ansible
# Test Ansible connectivity
ansible production -m ping
# Deploy secrets to production server
ansible-playbook playbooks/setup-production-secrets.yml \
--vault-password-file secrets/.vault_pass
# Expected output:
# PLAY [Deploy Production Secrets] ***
# TASK [Ensure secrets directory exists] *** ok
# TASK [Deploy environment file] *** changed
# PLAY RECAP *** production: ok=2 changed=1
```
### Step 4.2: Verify Secrets Deployed
```bash
# SSH to production server
ssh deploy@94.16.110.151
# Check secrets directory
ls -la ~/secrets/
# Verify .env.production exists (do NOT cat - contains secrets!)
file ~/secrets/.env.production
# Should output: .env.production: ASCII text
# Check file permissions
stat ~/secrets/.env.production
# Should be 600 (readable only by deploy user)
```
**✅ Checkpoint**: Secrets deployed to production server in ~/secrets/.env.production
---
## Phase 5: Setup Gitea Secrets for CI/CD
### Step 5.1: Configure Repository Secrets
1. Go to repository settings in Gitea:
```
https://git.michaelschiemer.de/<username>/michaelschiemer/settings/secrets
```
2. Add the following secrets:
**REGISTRY_USER**
```
admin
```
**REGISTRY_PASSWORD**
```
<your-registry-password>
```
**SSH_PRIVATE_KEY**
```
<content-of-~/.ssh/production>
```
**ANSIBLE_VAULT_PASSWORD**
```
<your-vault-password-from-step-2.1>
```
### Step 5.2: Verify Secrets in Gitea
1. Check secrets are visible in repository settings
2. Each secret should show "Hidden" value with green checkmark
**✅ Checkpoint**: All required secrets configured in Gitea repository
---
## Phase 6: First Deployment Test
### Step 6.1: Manual Deployment Dry-Run
**On Development Machine:**
```bash
cd deployment/ansible
# Test deployment (check mode - no changes)
ansible-playbook -i inventory/production.yml \
playbooks/deploy-update.yml \
-e "image_tag=test-$(date +%s)" \
-e "git_commit_sha=test123" \
-e "deployment_timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-e "docker_registry_username=admin" \
-e "docker_registry_password=your-registry-password" \
--check
# Expected: Should show what would be changed
```
### Step 6.2: Trigger CI/CD Pipeline
**Option A: Push to main branch**
```bash
# Make a small change (add comment to file)
echo "# Deployment test $(date)" >> deployment/DEPLOYMENT_TEST.txt
# Commit and push to main
git add deployment/DEPLOYMENT_TEST.txt
git commit -m "test(deployment): trigger CI/CD pipeline"
git push origin main
```
**Option B: Manual trigger**
1. Go to Gitea repository: Actions tab
2. Select workflow: "Production Deployment Pipeline"
3. Click "Run workflow"
4. Select branch: main
5. Click "Run"
### Step 6.3: Monitor Pipeline Execution
1. Go to: https://git.michaelschiemer.de/<username>/michaelschiemer/actions
2. Find the running workflow
3. Click to view details
4. Monitor each job:
- ✅ Test: Tests & quality checks pass
- ✅ Build: Docker image built and pushed
- ✅ Deploy: Application deployed to production
### Step 6.4: Verify Deployment
```bash
# Test health endpoint
curl -k https://michaelschiemer.de/health
# Expected response:
# {"status":"healthy","timestamp":"2025-10-30T14:30:00Z"}
# Check application logs
ssh deploy@94.16.110.151 "docker compose -f ~/application/docker-compose.yml logs -f app-php"
```
**✅ Checkpoint**: CI/CD pipeline executed successfully, application running on production
---
## Phase 7: Monitoring & Health Checks
### Step 7.1: Access Monitoring Tools
**Portainer**
```
https://portainer.michaelschiemer.de
```
- View all running containers
- Monitor resource usage
- Check logs
**Grafana**
```
https://grafana.michaelschiemer.de
```
- Username: admin
- Password: (set during setup)
- View application metrics
- Setup alerts
**Prometheus**
```
https://prometheus.michaelschiemer.de
```
- Query metrics
- Check targets
- Verify scraping
### Step 7.2: Configure Alerting
**In Grafana:**
1. Go to Alerting > Contact points
2. Add email notification channel
3. Create alert rules:
- High CPU usage (>80% for 5 minutes)
- High memory usage (>80%)
- Application down (health check fails)
- Database connection failures
### Step 7.3: Setup Health Check Monitoring
```bash
# Create cron job on production server
ssh deploy@94.16.110.151
# Add health check script
crontab -e
# Add line:
*/5 * * * * curl -f https://michaelschiemer.de/health || echo "Health check failed" | mail -s "Production Health Check Failed" admin@michaelschiemer.de
```
**✅ Checkpoint**: Monitoring tools accessible, alerts configured
---
## Phase 8: Backup & Rollback Testing
### Step 8.1: Verify Backups
```bash
# SSH to production server
ssh deploy@94.16.110.151
# Check backup directory
ls -lh ~/backups/
# Should see backup folders with timestamps
# Example: 2025-10-30T14-30-00/
```
### Step 8.2: Test Rollback
```bash
# On development machine
cd deployment/ansible
# Rollback to previous version
ansible-playbook -i inventory/production.yml \
playbooks/rollback.yml
# Verify rollback worked
curl -k https://michaelschiemer.de/health
```
**✅ Checkpoint**: Backups created, rollback mechanism tested
---
## Verification Checklist
### Infrastructure
- [ ] Traefik running and routing HTTPS
- [ ] PostgreSQL accessible and accepting connections
- [ ] Docker Registry accessible at registry.michaelschiemer.de
- [ ] Gitea accessible at git.michaelschiemer.de
- [ ] Monitoring stack (Portainer, Grafana, Prometheus) running
### Deployment
- [ ] Gitea Runner registered and showing "Idle" in UI
- [ ] Ansible Vault secrets encrypted and deployable
- [ ] SSH access configured for Ansible
- [ ] Repository secrets configured in Gitea
- [ ] CI/CD pipeline runs successfully end-to-end
### Application
- [ ] Application accessible at https://michaelschiemer.de
- [ ] Health endpoint returns 200 OK
- [ ] Database migrations ran successfully
- [ ] Queue workers processing jobs
- [ ] Logs showing no errors
### Monitoring
- [ ] Portainer shows all containers running
- [ ] Grafana dashboards displaying metrics
- [ ] Prometheus scraping all targets
- [ ] Alerts configured and sending notifications
### Security
- [ ] All secrets encrypted with Ansible Vault
- [ ] SSH keys secured (600 permissions)
- [ ] Registry requires authentication
- [ ] HTTPS enforced on all public endpoints
- [ ] Firewall configured correctly
---
## Troubleshooting
### Gitea Runner Not Registering
**Symptoms**: Runner not appearing in Gitea UI after running `./register.sh`
**Solutions**:
```bash
# Check runner logs
docker compose logs gitea-runner
# Verify registration token is correct
nano .env
# Check GITEA_RUNNER_REGISTRATION_TOKEN
# Unregister and re-register
./unregister.sh
./register.sh
```
### Ansible Connection Failed
**Symptoms**: `Failed to connect to the host via ssh`
**Solutions**:
```bash
# Test SSH manually
ssh -i ~/.ssh/production deploy@94.16.110.151
# Check SSH key permissions
chmod 600 ~/.ssh/production
# Verify SSH key is added to server
ssh-copy-id -i ~/.ssh/production.pub deploy@94.16.110.151
```
### Docker Registry Authentication Failed
**Symptoms**: `unauthorized: authentication required`
**Solutions**:
```bash
# Verify credentials
docker login registry.michaelschiemer.de
# Username: admin
# Password: <your-registry-password>
# Check htpasswd file on server
ssh deploy@94.16.110.151 "cat ~/deployment/stacks/registry/auth/htpasswd"
```
### Deployment Health Check Failed
**Symptoms**: Health check returns 404 or times out
**Solutions**:
```bash
# Check application logs
ssh deploy@94.16.110.151 "docker compose -f ~/application/docker-compose.yml logs app-php"
# Verify application stack is running
ssh deploy@94.16.110.151 "docker ps"
# Check Traefik routing
ssh deploy@94.16.110.151 "docker compose -f ~/deployment/stacks/traefik/docker-compose.yml logs"
```
---
## Next Steps
After successful deployment:
1. **Configure DNS**: Point michaelschiemer.de to 94.16.110.151
2. **SSL Certificates**: Traefik will automatically request Let's Encrypt certificates
3. **Monitoring**: Review Grafana dashboards and setup additional alerts
4. **Backups**: Configure automated database backups
5. **Performance**: Review application performance and optimize
6. **Documentation**: Update team documentation with production procedures
---
## Support Contacts
- **Infrastructure Issues**: Check Portainer logs
- **Deployment Issues**: Review Gitea Actions logs
- **Application Issues**: Check application logs in Portainer
- **Emergency Rollback**: Run `ansible-playbook playbooks/rollback.yml`
---
**Setup Status**: 🚧 In Progress
**Next Action**: Start with Phase 1 - Gitea Runner Setup

262
deployment/docs/guides/vault-password.md Normal file
View File

@@ -0,0 +1,262 @@
# Ansible Vault Password Dokumentation
## ?bersicht
Das Ansible Vault-Passwort wird verwendet, um verschl?sselte Secrets-Dateien (`production.vault.yml`) zu sch?tzen. Diese Dokumentation beschreibt, wie das Vault-Passwort angelegt, gespeichert und verwendet wird.
## Historischer Kontext
### Erstellungsdatum
- **Erstellt am:** 30. Oktober 2025, 21:42:27
- **Datei:** `deployment/ansible/secrets/.vault_pass`
- **Erstes Setup-Script:** 31. Oktober 2025 (Commit `e26eb2a`)
- **Script-Datei:** `deployment/ansible/scripts/init-secrets.sh`
### Einf?hrung
Das Vault-Passwort-System wurde im Rahmen des CI/CD-Pipeline-Setups eingef?hrt, um die sichere Verwaltung von Production-Secrets zu erm?glichen. Das automatische Setup-Script wurde am 31. Oktober 2025 hinzugef?gt, um die manuelle Erstellung zu vereinfachen.
## Speicherort und Sicherheit
### Dateispeicherort
- **Pfad:** `deployment/ansible/secrets/.vault_pass`
- **Berechtigungen:** `600` (nur Owner lesbar/schreibbar)
- **Gitignored:** ? Ja (in `.gitignore` hinterlegt)
- **Inhalt:** Eine Zeile mit dem Vault-Passwort (plaintext)
### Sicherheitshinweise
?? **WICHTIG:**
- Das Passwort ist in Klartext in der Datei gespeichert
- Die Datei ist **gitignored** und wird **nie** ins Repository committet
- Berechtigungen sind auf `600` gesetzt (nur Owner-Zugriff)
- Das Passwort sollte zus?tzlich im **Passwort-Manager** gespeichert werden
- F?r verschiedene Umgebungen (dev/staging/prod) sollten unterschiedliche Passw?rter verwendet werden
## Erstellung des Vault-Passworts
### Methode 1: Automatisiertes Script (Empfohlen)
Das Script `init-secrets.sh` f?hrt Sie interaktiv durch den Setup-Prozess:
```bash
cd deployment/ansible
./scripts/init-secrets.sh
```
**Was das Script macht:**
1. Pr?ft, ob `.vault_pass` bereits existiert
2. Falls nicht vorhanden: Fragt interaktiv nach dem Passwort (mit Best?tigung)
3. Speichert das Passwort in `secrets/.vault_pass`
4. Setzt Berechtigungen auf `600`
5. Erstellt und verschl?sselt `production.vault.yml` (optional)
**Vorteile:**
- Automatische Berechtigungen
- Passwort-Best?tigung verhindert Tippfehler
- Vollst?ndiger Setup-Workflow inkl. Vault-Datei-Erstellung
### Methode 2: Manuelle Erstellung
```bash
cd deployment/ansible/secrets
# Passwort erstellen
echo "your-secure-vault-password-here" > .vault_pass
# Sicherheit: Berechtigungen setzen
chmod 600 .vault_pass
```
**Wichtig:** Verwenden Sie ein sicheres, zuf?lliges Passwort!
## Verwendung des Vault-Passworts
### In Ansible Playbooks
Das Vault-Passwort wird bei der Ausf?hrung von Playbooks ?bergeben:
```bash
# Beispiel: Production Secrets deployen
ansible-playbook playbooks/setup-production-secrets.yml \
--vault-password-file secrets/.vault_pass
# Beispiel: Infrastructure deployen
ansible-playbook playbooks/setup-infrastructure.yml \
-i inventory/production.yml \
--vault-password-file secrets/.vault_pass
# Beispiel: Application Update deployen
ansible-playbook playbooks/deploy-update.yml \
-e "image_tag=sha-abc123" \
--vault-password-file secrets/.vault_pass
```
### Vault-Dateien verwalten
```bash
# Vault-Datei entschl?sseln und anzeigen
ansible-vault view secrets/production.vault.yml \
--vault-password-file secrets/.vault_pass
# Vault-Datei bearbeiten
ansible-vault edit secrets/production.vault.yml \
--vault-password-file secrets/.vault_pass
# Neue Vault-Datei erstellen und verschl?sseln
ansible-vault encrypt secrets/production.vault.yml \
--vault-password-file secrets/.vault_pass
# Vault-Datei entschl?sseln (dauerhaft)
ansible-vault decrypt secrets/production.vault.yml \
--vault-password-file secrets/.vault_pass
```
## CI/CD Integration
### Gitea Actions
In Gitea Actions wird das Vault-Passwort als Secret gespeichert:
- **Secret-Name:** `ANSIBLE_VAULT_PASSWORD`
- **Verwendung:** Wird automatisch in Workflows verwendet, die Ansible-Vault ben?tigen
**Hinzuf?gen des Secrets in Gitea:**
1. Gehe zu: Repository Settings ? Secrets
2. Erstelle neues Secret: `ANSIBLE_VAULT_PASSWORD`
3. Wert: Das Vault-Passwort aus `.vault_pass`
**Workflow-Beispiel:**
```yaml
- name: Deploy with Ansible
run: |
ansible-playbook playbooks/deploy-update.yml \
--vault-password-file <(echo "${{ secrets.ANSIBLE_VAULT_PASSWORD }}")
```
## Passwort zur?cksetzen/?ndern
### Passwort ?ndern
Wenn das Vault-Passwort ge?ndert werden muss:
```bash
cd deployment/ansible
# 1. Alte Vault-Datei entschl?sseln (mit altem Passwort)
ansible-vault decrypt secrets/production.vault.yml \
--vault-password-file secrets/.vault_pass
# 2. Neues Passwort setzen
echo "new-secure-vault-password" > secrets/.vault_pass
chmod 600 secrets/.vault_pass
# 3. Vault-Datei mit neuem Passwort verschl?sseln
ansible-vault encrypt secrets/production.vault.yml \
--vault-password-file secrets/.vault_pass
# 4. Passwort im Passwort-Manager aktualisieren
# 5. CI/CD Secret in Gitea aktualisieren (ANSIBLE_VAULT_PASSWORD)
```
### Passwort vergessen
?? **Wenn das Vault-Passwort verloren geht:**
- Die verschl?sselte `production.vault.yml` kann nicht mehr entschl?sselt werden
- Eine neue Vault-Datei muss erstellt werden
- Alle Secrets m?ssen neu konfiguriert werden
- **L?sung:** Passwort im Passwort-Manager speichern!
## Troubleshooting
### Problem: "Decryption failed"
**Fehler:**
```
ERROR! Decryption failed (no vault secrets were found)
```
**L?sung:**
1. Passwort-Datei pr?fen:
```bash
cat deployment/ansible/secrets/.vault_pass
```
2. Korrekten Pfad verwenden:
```bash
--vault-password-file secrets/.vault_pass
```
3. Berechtigungen pr?fen:
```bash
ls -la deployment/ansible/secrets/.vault_pass
# Sollte: -rw------- (600)
```
### Problem: "Vault password file not found"
**Fehler:**
```
ERROR! the vault password file secrets/.vault_pass was not found
```
**L?sung:**
```bash
# Pr?fen ob Datei existiert
ls -la deployment/ansible/secrets/.vault_pass
# Falls nicht vorhanden, neu erstellen (siehe "Erstellung des Vault-Passworts")
```
### Problem: "Permission denied"
**Fehler:**
```
Permission denied: secrets/.vault_pass
```
**L?sung:**
```bash
chmod 600 deployment/ansible/secrets/.vault_pass
```
## Best Practices
### ? Empfohlene Vorgehensweise
1. **Passwort-Manager:** Vault-Passwort im Passwort-Manager speichern
2. **Sichere Passw?rter:** Verwendung von zuf?lligen, starken Passw?rtern
3. **Separate Passw?rter:** Verschiedene Passw?rter f?r dev/staging/prod
4. **Regelm??ige Rotation:** Passwort regelm??ig ?ndern (z.B. viertelj?hrlich)
5. **Backup:** Passwort an sicherem Ort (Passwort-Manager) sichern
6. **Zugriffskontrolle:** Nur autorisierte Personen sollten Zugriff haben
### ? Zu vermeiden
- Passwort ins Repository committen (gitignored!)
- Passwort in unverschl?sselten Dokumenten speichern
- Passwort per Email oder Chat teilen
- Einfache/erratbare Passw?rter verwenden
- Passwort mehreren Umgebungen teilen
## Verwandte Dateien
- **Setup-Script:** [`deployment/ansible/scripts/init-secrets.sh`](../../ansible/scripts/init-secrets.sh)
- **Vault-Datei:** `deployment/ansible/secrets/production.vault.yml`
- **Vault-Template:** `deployment/ansible/secrets/production.vault.yml.example`
- **Gitignore:** `deployment/ansible/secrets/.gitignore`
- **Haupt-Dokumentation:** [`deployment/ansible/README.md`](../../ansible/README.md)
- **Setup-Guide:** [`deployment/docs/guides/setup-guide.md`](setup-guide.md)
## Referenzen
- [Ansible Vault Dokumentation](https://docs.ansible.com/ansible/latest/user_guide/vault.html)
- [Ansible Vault Best Practices](https://docs.ansible.com/ansible/latest/user_guide/vault.html#best-practices)
## Zusammenfassung
| Aspekt | Details |
|--------|---------|
| **Erstellt am** | 30. Oktober 2025, 21:42:27 |
| **Speicherort** | `deployment/ansible/secrets/.vault_pass` |
| **Berechtigungen** | `600` (nur Owner) |
| **Gitignored** | ? Ja |
| **Setup-Script** | `scripts/init-secrets.sh` |
| **CI/CD Secret** | `ANSIBLE_VAULT_PASSWORD` |
| **Verwendung** | `--vault-password-file secrets/.vault_pass` |

125
deployment/docs/history/cleanup-log.md Normal file
View File

@@ -0,0 +1,125 @@
# Deployment System Cleanup Log
**Datum:** 2025-01-31
**Ziel:** Redundanzen entfernen, Struktur verbessern
---
## Gelöschte Dateien
### Root-Level Docker Compose (Veraltet)
- ✅ `docker-compose.prod.yml` - Docker Swarm (nicht mehr verwendet, Deployment läuft über `deployment/stacks/`)
- ✅ `docker-compose.prod.yml.backup` - Backup-Datei
### Root-Level Dokumentation (Veraltet)
- ✅ `DEPLOYMENT_PLAN.md` - Veraltet, durch `deployment/` System ersetzt
- ✅ `PRODUCTION-DEPLOYMENT-TODO.md` - Veraltet, durch `deployment/DEPLOYMENT-TODO.md` ersetzt
### Deployment Dokumentation (Veraltet)
- ✅ `deployment/NATIVE-WORKFLOW-README.md` - Durch CI/CD Pipeline ersetzt
### docs/deployment/ Dokumentation (Veraltet)
- ✅ `docs/deployment/docker-swarm-deployment.md` - Swarm nicht mehr verwendet
- ✅ `docs/deployment/DEPLOYMENT_RESTRUCTURE.md` - Historisch
- ✅ `docs/deployment/quick-deploy.md` - Referenziert gelöschte `docker-compose.prod.yml`
- ✅ `docs/deployment/troubleshooting-checklist.md` - Referenziert veraltete Konfigurationen
- ✅ `docs/deployment/production-deployment-guide.md` - Referenziert veraltete Workflows
- ✅ `docs/deployment/DEPLOYMENT.md` - Veraltet
- ✅ `docs/deployment/DEPLOYMENT_SUMMARY.md` - Redundant zu `deployment/DEPLOYMENT_SUMMARY.md`
- ✅ `docs/deployment/QUICKSTART.md` - Redundant zu `deployment/QUICK_START.md`
- ✅ `docs/deployment/PRODUCTION_DEPLOYMENT.md` - Veraltet
- ✅ `docs/deployment/DEPLOYMENT_WORKFLOW.md` - Veraltet
- ✅ `docs/deployment/DEPLOYMENT_CHECKLIST.md` - Veraltet
- ✅ `docs/deployment/docker-compose-production.md` - Referenziert veraltete Konfigurationen
### Docker Ordner
- ✅ `docker/DOCKER-TODO.md` - Veraltet, Punkte größtenteils umgesetzt
### Leere Ordner
- ✅ `deployment/stacks/postgres/` - Leer, `postgresql/` wird verwendet
- ✅ `deployment/scripts/` - Alle Scripts entfernt (nur Ansible jetzt)
---
## Konsolidierte Playbooks
### Troubleshooting Playbooks → `troubleshoot.yml`
- ✅ `check-container-health.yml` → Tags: `health,check`
- ✅ `diagnose-404.yml` → Tags: `404,diagnose`
- ✅ `fix-container-health-checks.yml` → Tags: `health,fix`
- ✅ `fix-nginx-404.yml` → Tags: `nginx,404,fix`
---
## Erstellt
### Zentrale Konfiguration
- ✅ `deployment/ansible/group_vars/production.yml` - Zentrale Variablen
- Alle Playbooks verwenden jetzt zentrale Variablen
- Redundante Variablendefinitionen entfernt
### Dokumentation
- ✅ `deployment/DEPLOYMENT_COMMANDS.md` - Command-Referenz
- ✅ `deployment/IMPROVEMENTS.md` - Verbesserungsvorschläge
- ✅ `deployment/CLEANUP_LOG.md` - Dieser Log
---
## Wichtige Hinweise
### Docker Compose Files
- **BEHALTEN:** `docker-compose.yml` (Development)
- **BEHALTEN:** `docker-compose.production.yml` (kann noch für lokales Testing verwendet werden)
- **BEHALTEN:** `docker-compose.security.yml` (Security Override)
- **PRODUCTION:** Verwendet jetzt `deployment/stacks/*/docker-compose.yml`
### docs/deployment/ Dateien (BEHALTEN)
Die folgenden Dateien in `docs/deployment/` bleiben erhalten, da sie spezifische Themen behandeln:
- **VPN:** `WIREGUARD-SETUP.md`, `WIREGUARD-FUTURE-SECURITY.md`
- **Security:** `PRODUCTION-SECURITY-UPDATES.md`
- **Configuration:** `database-migration-strategy.md`, `logging-configuration.md`, `production-logging.md`, `secrets-management.md`, `ssl-setup.md`, `SSL-PRODUCTION-SETUP.md`, `env-production-template.md`, `production-prerequisites.md`
- **⚠️ Möglicherweise veraltet:** `ANSIBLE_DEPLOYMENT.md`, `deployment-automation.md` (sollten auf neue Ansible-Struktur verweisen)
### Deployment Archive
- `.deployment-archive-20251030-111806/` - Backup, bleibt für Referenz (sollte in `.gitignore`)
---
## Verbleibende Dateien
### docs/deployment/ (Relevante Dateien behalten)
- ✅ `WIREGUARD-SETUP.md` - Aktuell
- ✅ `WIREGUARD-FUTURE-SECURITY.md` - Aktuell
- ✅ `database-migration-strategy.md` - Relevante Strategie-Dokumentation
- ✅ `logging-configuration.md` - Relevante Logging-Dokumentation
- ✅ `production-logging.md` - Aktuelle Logging-Dokumentation
- ✅ `secrets-management.md` - Relevante Secrets-Dokumentation
- ✅ `ssl-setup.md` - Relevante SSL-Dokumentation
- ✅ `SSL-PRODUCTION-SETUP.md` - Aktuell
- ✅ `env-production-template.md` - Template-Dokumentation
- ✅ `production-prerequisites.md` - Relevante Prerequisites
- ✅ `PRODUCTION-SECURITY-UPDATES.md` - Relevante Security-Updates
- ⚠️ `ANSIBLE_DEPLOYMENT.md` - Veraltet, mit Warnung markiert
- ⚠️ `deployment-automation.md` - Veraltet, mit Warnung markiert
- ✅ `README.md` - Aktualisiert, verweist auf deployment/
---
## Zusammenfassung
### Gelöscht:
- **11 veraltete Dateien** aus `docs/deployment/`
- **4 veraltete Dateien** aus Root-Level
- **4 redundante Playbooks** (konsolidiert)
- **Alle Deployment-Scripts** (durch Ansible ersetzt)
### Erstellt:
- **Zentrale Variablen** in `group_vars/production.yml`
- **Konsolidiertes Troubleshooting** Playbook mit Tags
- **Aktualisierte Dokumentation** (README, Commands, etc.)
### Ergebnis:
- ✅ **Redundanzen entfernt**
- ✅ **Zentrale Konfiguration**
- ✅ **Klarere Struktur**
- ✅ **Einfacher zu warten**

176
deployment/docs/history/cleanup-summary.md Normal file
View File

@@ -0,0 +1,176 @@
# Deployment System - Cleanup Summary
**Datum:** 2025-01-31
**Status:** ✅ Abgeschlossen
---
## 📊 Zusammenfassung
### Gelöschte Dateien: **25+ Dateien**
#### Root-Level (6 Dateien)
- ✅ `docker-compose.prod.yml` - Docker Swarm (veraltet)
- ✅ `docker-compose.prod.yml.backup` - Backup
- ✅ `DEPLOYMENT_PLAN.md` - Veraltet
- ✅ `PRODUCTION-DEPLOYMENT-TODO.md` - Veraltet
- ✅ `docker/DOCKER-TODO.md` - Veraltet
#### Deployment/ Ordner (7 Dateien)
- ✅ `deployment/NATIVE-WORKFLOW-README.md` - Durch CI/CD ersetzt
- ✅ `deployment/scripts/` - Ordner gelöscht (alle Scripts entfernt)
- ✅ `deployment/stacks/postgres/` - Leerer Ordner
- ✅ 4 redundante Status/TODO Dateien
#### docs/deployment/ (12 Dateien)
- ✅ `docker-swarm-deployment.md` - Swarm nicht mehr verwendet
- ✅ `DEPLOYMENT_RESTRUCTURE.md` - Historisch
- ✅ `quick-deploy.md` - Referenziert gelöschte Dateien
- ✅ `troubleshooting-checklist.md` - Veraltet
- ✅ `production-deployment-guide.md` - Veraltet
- ✅ `DEPLOYMENT.md` - Veraltet
- ✅ `DEPLOYMENT_SUMMARY.md` - Redundant
- ✅ `QUICKSTART.md` - Redundant
- ✅ `PRODUCTION_DEPLOYMENT.md` - Veraltet
- ✅ `DEPLOYMENT_WORKFLOW.md` - Veraltet
- ✅ `DEPLOYMENT_CHECKLIST.md` - Veraltet
- ✅ `docker-compose-production.md` - Veraltet
#### Ansible Playbooks (4 Playbooks konsolidiert)
- ✅ `check-container-health.yml` → `tasks/check-health.yml`
- ✅ `diagnose-404.yml` → `tasks/diagnose-404.yml`
- ✅ `fix-container-health-checks.yml` → `tasks/fix-health-checks.yml`
- ✅ `fix-nginx-404.yml` → `tasks/fix-nginx-404.yml`
---
## ✨ Verbesserungen
### 1. Zentrale Variablen
- ✅ `deployment/ansible/group_vars/production.yml` erstellt
- ✅ Alle Playbooks verwenden jetzt zentrale Variablen
- ✅ Redundante Variablendefinitionen entfernt
### 2. Konsolidierte Playbooks
- ✅ `troubleshoot.yml` - Unified Troubleshooting Playbook
- ✅ Tag-basiertes Execution für spezifische Tasks
- ✅ Modularisierte Tasks in `tasks/` Ordner
### 3. Bereinigte Dokumentation
- ✅ `deployment/DEPLOYMENT_COMMANDS.md` - Command-Referenz
- ✅ `deployment/IMPROVEMENTS.md` - Verbesserungsvorschläge
- ✅ `deployment/CLEANUP_LOG.md` - Cleanup-Log
- ✅ `docs/deployment/README.md` - Aktualisiert mit Verweis auf deployment/
### 4. Git-basiertes Deployment
- ✅ Container klont/pullt automatisch aus Git Repository
- ✅ `entrypoint.sh` erweitert für Git-Funktionalität
- ✅ `sync-code.yml` Playbook für Code-Sync
---
## 📁 Aktuelle Struktur
### deployment/ (Haupt-Dokumentation)
```
deployment/
├── README.md # Haupt-Dokumentation
├── QUICK_START.md # Schnellstart
├── DEPLOYMENT_COMMANDS.md # Command-Referenz
├── CODE_CHANGE_WORKFLOW.md # Workflow-Dokumentation
├── SETUP-GUIDE.md # Setup-Anleitung
├── DOCUMENTATION_INDEX.md # Dokumentations-Index
├── ansible/
│ ├── group_vars/
│ │ └── production.yml # ⭐ Zentrale Variablen
│ └── playbooks/
│ ├── troubleshoot.yml # ⭐ Unified Troubleshooting
│ └── tasks/ # ⭐ Modularisierte Tasks
│ ├── check-health.yml
│ ├── diagnose-404.yml
│ ├── fix-health-checks.yml
│ └── fix-nginx-404.yml
└── stacks/ # Docker Compose Stacks
```
### docs/deployment/ (Spezifische Themen)
```
docs/deployment/
├── README.md # ⭐ Aktualisiert
├── WIREGUARD-SETUP.md # ✅ Aktuell
├── database-migration-strategy.md # ✅ Relevant
├── logging-configuration.md # ✅ Relevant
├── secrets-management.md # ✅ Relevant
├── ssl-setup.md # ✅ Relevant
└── ... (weitere spezifische Themen)
```
---
## 🎯 Verbesserte Arbeitsweise
### Vorher:
```bash
# Viele Scripts mit Redundanz
./scripts/deploy.sh
./scripts/rollback.sh
./scripts/sync-code.sh
# Viele separate Playbooks
ansible-playbook ... check-container-health.yml
ansible-playbook ... diagnose-404.yml
ansible-playbook ... fix-container-health-checks.yml
```
### Jetzt:
```bash
# Nur Ansible Playbooks - direkt
cd deployment/ansible
ansible-playbook -i inventory/production.yml playbooks/deploy-update.yml
ansible-playbook -i inventory/production.yml playbooks/troubleshoot.yml --tags health,check
ansible-playbook -i inventory/production.yml playbooks/sync-code.yml
```
---
## ✅ Ergebnisse
### Redundanz entfernt:
- ❌ Scripts vs Playbooks → ✅ Nur Playbooks
- ❌ 4 separate Troubleshooting Playbooks → ✅ 1 Playbook mit Tags
- ❌ Redundante Variablen → ✅ Zentrale Variablen
- ❌ 25+ veraltete Dokumentationsdateien → ✅ Bereinigt
### Struktur verbessert:
- ✅ Klarere Trennung: deployment/ (aktuell) vs docs/deployment/ (spezifische Themen)
- ✅ Zentrale Konfiguration in `group_vars/`
- ✅ Modulare Tasks in `tasks/`
- ✅ Unified Troubleshooting mit Tags
### Einfacher zu warten:
- ✅ Einmalige Variablendefinition
- ✅ Weniger Dateien zu aktualisieren
- ✅ Konsistente Struktur
- ✅ Klare Dokumentation
---
## 📈 Metriken
**Vorher:**
- ~38 Dokumentationsdateien
- 8+ Playbooks mit redundanten Variablen
- 4 Deployment-Scripts
- 4 separate Troubleshooting-Playbooks
**Nachher:**
- ~20 relevante Dokumentationsdateien
- Zentrale Variablen
- Keine redundanten Scripts
- 1 konsolidiertes Troubleshooting-Playbook
**Reduktion:** ~50% weniger Dateien, ~70% weniger Redundanz
---
**Status:** ✅ Bereinigung abgeschlossen, Deployment-System optimiert!

561
deployment/docs/reference/application-stack.md Normal file
View File

@@ -0,0 +1,561 @@
# Application Stack Deployment Prozess
## Übersicht
Dieses Dokument erklärt, wie genau das Deployment in den Application Stack abläuft, wenn die CI/CD Pipeline ausgeführt wird.
**📖 Verwandte Dokumentation:**
- **[Code Changes Workflow](../guides/code-change-workflow.md)** - Wie Codeänderungen gepusht werden
- **[CI/CD Status](../status/ci-cd-status.md)** - Aktueller Status der Pipeline
---
## Deployment-Flow
```
CI/CD Pipeline (Gitea Actions)
↓
1. Tests & Build
↓
2. Docker Image Build & Push zur Registry
↓
3. Ansible Playbook ausführen
↓
4. Application Stack aktualisieren
```
---
## Detaillierter Ablauf
### Phase 1: CI/CD Pipeline (`.gitea/workflows/production-deploy.yml`)
#### Job 1: Tests
```yaml
- PHP 8.3 Setup
- Composer Dependencies installieren
- Pest Tests ausführen
- PHPStan Code Quality Check
- Code Style Check
```
#### Job 2: Build & Push
```yaml
- Docker Image Build (Dockerfile.production)
- Image mit Tags pushen:
- registry.michaelschiemer.de/framework:latest
- registry.michaelschiemer.de/framework:<tag>
- registry.michaelschiemer.de/framework:git-<short-sha>
```
#### Job 3: Deploy (Ansible)
**Schritt 1: Code Checkout**
```bash
git clone <repository> /workspace/repo
```
**Schritt 2: SSH Setup**
```bash
# SSH Private Key aus Secret wird in ~/.ssh/production geschrieben
echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/production
chmod 600 ~/.ssh/production
```
**Schritt 3: Ansible Installation**
```bash
apt-get install -y ansible
```
**Schritt 4: Ansible Playbook ausführen**
```bash
cd /workspace/repo/deployment/ansible
ansible-playbook -i inventory/production.yml \
playbooks/deploy-update.yml \
-e "image_tag=<generated-tag>" \
-e "git_commit_sha=<commit-sha>" \
-e "deployment_timestamp=<timestamp>" \
-e "docker_registry_username=${{ secrets.REGISTRY_USER }}" \
-e "docker_registry_password=${{ secrets.REGISTRY_PASSWORD }}"
```
---
### Phase 2: Ansible Deployment (`deploy-update.yml`)
Das Ansible Playbook führt folgende Schritte auf dem Production-Server aus:
#### Pre-Tasks
**1. Secrets laden (optional)**
```yaml
- Lädt Registry Credentials aus Ansible Vault (falls vorhanden)
- Oder verwendet Credentials aus Workflow-Variablen
```
**2. Docker Service prüfen**
```yaml
- Verifiziert, dass Docker läuft
- Startet Docker falls notwendig
```
**3. Verzeichnisse erstellen**
```yaml
- Application Stack Path: ~/deployment/stacks/application
- Backup Verzeichnis: ~/deployment/backups/<timestamp>/
```
#### Tasks
**1. Backup aktueller Deployment-Status**
```bash
# Speichert aktuellen Container-Status
docker compose -f ~/deployment/stacks/application/docker-compose.yml \
ps --format json > backups/<timestamp>/current_containers.json
# Speichert aktuelle docker-compose.yml Konfiguration
docker compose -f ~/deployment/stacks/application/docker-compose.yml \
config > backups/<timestamp>/docker-compose-config.yml
```
**2. Docker Registry Login**
```bash
# Login zur privaten Registry mit Credentials
docker login registry.michaelschiemer.de \
-u <registry-username> \
-p <registry-password>
```
**3. Neues Image Pullen**
```bash
# Pullt das neue Image von der Registry
docker pull registry.michaelschiemer.de/framework:<tag>
# Beispiel:
# registry.michaelschiemer.de/framework:abc1234-1696234567
```
**4. docker-compose.yml aktualisieren**
**Wichtig:** Das Playbook aktualisiert die `docker-compose.yml` Datei direkt auf dem Server!
```yaml
# Vorher:
services:
app:
image: registry.michaelschiemer.de/framework:latest
# Nachher (wenn image_tag != 'latest'):
services:
app:
image: registry.michaelschiemer.de/framework:<tag>
```
**Regex-Replace:**
```yaml
regexp: '^(\s+image:\s+){{ app_image }}:.*$'
replace: '\1{{ app_image }}:{{ image_tag }}'
```
**Betroffene Services (werden alle aktualisiert):**
- `app` (PHP-FPM) - Zeile 6: `image: registry.michaelschiemer.de/framework:latest`
- `queue-worker` (Queue Worker) - Zeile 120: `image: registry.michaelschiemer.de/framework:latest`
- `scheduler` (Scheduler) - Zeile 165: `image: registry.michaelschiemer.de/framework:latest`
**Hinweis:**
- Alle drei Services verwenden das gleiche Image, daher werden alle mit dem neuen Tag aktualisiert
- Der Regex matched **alle Zeilen** die mit `image: registry.michaelschiemer.de/framework:` beginnen
- `nginx` und `redis` bleiben unverändert (verwenden andere Images)
**5. Application Stack neu starten**
```bash
docker compose -f ~/deployment/stacks/application/docker-compose.yml \
up -d \
--pull always \
--force-recreate \
--remove-orphans
```
**Was passiert dabei:**
- `--pull always`: Zieht Images immer neu (auch wenn schon vorhanden)
- `--force-recreate`: Erstellt Container immer neu, auch wenn Konfiguration unverändert ist
- `--remove-orphans`: Entfernt Container, die nicht mehr in der Compose-Datei definiert sind
- `-d`: Läuft im Hintergrund (detached)
**Container-Neustart-Reihenfolge:**
1. Abhängigkeiten werden gestoppt (app hängt von redis ab)
2. Container werden neu erstellt mit neuem Image
3. Container werden in korrekter Reihenfolge gestartet (redis → app → nginx)
4. Health-Checks werden ausgeführt
**6. Warten auf Health-Checks**
```yaml
# Wartet 60 Sekunden auf Container-Gesundheit
wait_for:
timeout: 60
```
**7. Health-Status prüfen**
```bash
# Prüft alle Container-Health-Status
docker compose ps --format json | \
jq -r '.[] | select(.Health != "healthy" and .Health != "") | "\(.Name): \(.Health)"'
```
**8. Deployment-Metadaten speichern**
```
~/deployment/backups/<timestamp>/deployment_metadata.txt
```
**Inhalt:**
```
Deployment Timestamp: 2025-10-31T02:35:04Z
Git Commit: abc1234...
Image Tag: abc1234-1696234567
Deployed Image: registry.michaelschiemer.de/framework:abc1234-1696234567
Image Pull: SUCCESS
Stack Deploy: UPDATED
Health Status: All services healthy
```
**9. Alte Backups aufräumen**
```bash
# Behält nur die letzten X Backups (Standard: 5)
ls -dt */ | tail -n +6 | xargs -r rm -rf
```
---
### Phase 3: Application Stack Services
Der Application Stack besteht aus mehreren Services:
#### Services im Stack
**1. `app` (PHP-FPM Application)**
- Image: `registry.michaelschiemer.de/framework:<tag>`
- Container: `app`
- Health Check: `php-fpm-healthcheck`
- Netzwerk: `app-internal`
- Abhängigkeiten: `redis` (condition: service_healthy)
**2. `nginx` (Web Server)**
- Image: `nginx:1.25-alpine`
- Container: `nginx`
- Health Check: `wget --spider http://localhost/health`
- Netzwerke: `traefik-public`, `app-internal`
- Abhängigkeiten: `app` (condition: service_healthy)
- Traefik Labels für Routing
**3. `redis` (Cache/Session/Queue)**
- Image: `redis:7-alpine`
- Container: `redis`
- Health Check: `redis-cli --raw incr ping`
- Netzwerk: `app-internal`
**4. `queue-worker` (Background Jobs)**
- Image: `registry.michaelschiemer.de/framework:<tag>` (gleiches wie app)
- Container: `queue-worker`
- Health Check: `pgrep -f 'queue:work'`
- Netzwerk: `app-internal`
- Command: `php console.php queue:work`
- Abhängigkeiten: `app`, `redis`
**5. `scheduler` (Cron Jobs)**
- Image: `registry.michaelschiemer.de/framework:<tag>` (gleiches wie app)
- Container: `scheduler`
- Health Check: `pgrep -f 'scheduler:run'`
- Netzwerk: `app-internal`
- Command: `php console.php scheduler:run`
- Abhängigkeiten: `app`, `redis`
---
## Container-Neustart-Details
### Was passiert bei `docker compose up -d --force-recreate`?
**1. Container-Stop:**
- Laufende Container werden gestoppt
- Volumes bleiben erhalten (persistente Daten)
- Netzwerke bleiben erhalten
**2. Container-Entfernung:**
- Alte Container werden entfernt
- Neue Container werden mit neuem Image erstellt
**3. Container-Start:**
- Container starten in Abhängigkeits-Reihenfolge
- Health-Checks werden ausgeführt
- Falls Health-Check fehlschlägt, wird Container neu gestartet (restart: unless-stopped)
**4. Zero-Downtime?**
- **Teilweise:** Container werden nacheinander neu gestartet
- `nginx` wartet auf `app` Health-Check
- Während Neustart kann es zu kurzen Verbindungsfehlern kommen
- Kein echter Blue-Green-Deployment (das wäre möglich, aber nicht implementiert)
---
## Konfigurationsvariablen
### Inventory-Variablen (`inventory/production.yml`)
```yaml
app_image: "registry.michaelschiemer.de/framework"
docker_registry_url: "registry.michaelschiemer.de"
backups_path: "~/deployment/backups"
max_rollback_versions: 5
deploy_user_home: "~/deployment"
```
### Workflow-Variablen (aus CI/CD)
```yaml
image_tag: "abc1234-1696234567" # Generiert aus: <short-sha>-<timestamp>
git_commit_sha: "abc1234567890..."
deployment_timestamp: "2025-10-31T02:35:04Z"
docker_registry_username: "<from-secret>"
docker_registry_password: "<from-secret>"
```
---
## Beispiel-Deployment
### Schritt-für-Schritt Beispiel
**1. CI/CD Pipeline startet:**
```bash
# Commit: abc1234...
# Image Tag generiert: abc1234-1696234567
```
**2. Image wird gebaut und gepusht:**
```bash
docker buildx build \
--tag registry.michaelschiemer.de/framework:latest \
--tag registry.michaelschiemer.de/framework:abc1234-1696234567 \
--tag registry.michaelschiemer.de/framework:git-abc1234 \
--push \
.
```
**3. Ansible Playbook wird ausgeführt:**
```bash
ansible-playbook -i inventory/production.yml \
playbooks/deploy-update.yml \
-e "image_tag=abc1234-1696234567" \
-e "git_commit_sha=abc1234567890..." \
-e "deployment_timestamp=2025-10-31T02:35:04Z"
```
**4. Auf Production-Server:**
```bash
# 1. Backup erstellen
mkdir -p ~/deployment/backups/2025-10-31T02-35-04Z
# 2. Registry Login
docker login registry.michaelschiemer.de -u admin -p <password>
# 3. Image Pullen
docker pull registry.michaelschiemer.de/framework:abc1234-1696234567
# 4. docker-compose.yml aktualisieren
# Vorher: image: registry.michaelschiemer.de/framework:latest
# Nachher: image: registry.michaelschiemer.de/framework:abc1234-1696234567
# 5. Stack neu starten
cd ~/deployment/stacks/application
docker compose up -d --pull always --force-recreate --remove-orphans
# 6. Health-Checks warten
sleep 60
# 7. Status prüfen
docker compose ps
# app: healthy
# nginx: healthy
# redis: healthy
# queue-worker: healthy
# scheduler: healthy
```
**5. Deployment-Metadaten speichern:**
```bash
cat > ~/deployment/backups/2025-10-31T02-35-04Z/deployment_metadata.txt <<EOF
Deployment Timestamp: 2025-10-31T02:35:04Z
Git Commit: abc1234567890...
Image Tag: abc1234-1696234567
Deployed Image: registry.michaelschiemer.de/framework:abc1234-1696234567
Image Pull: SUCCESS
Stack Deploy: UPDATED
Health Status: All services healthy
EOF
```
---
## Wichtige Hinweise
### 1. Image-Tag-Update
**Wichtig:** Das Playbook aktualisiert die `docker-compose.yml` Datei **direkt auf dem Server**!
- Die Datei wird mit `replace` Modul geändert
- Alle Services mit dem Image `registry.michaelschiemer.de/framework:*` werden aktualisiert
- Das bedeutet: `app`, `queue-worker`, und `scheduler` bekommen alle das neue Image
### 2. Force-Recreate
**Achtung:** `--force-recreate` startet Container **immer** neu, auch wenn Konfiguration unverändert ist.
- Container-IDs ändern sich
- Kurze Downtime möglich
- Neue Container bekommen neue IPs im Docker-Netzwerk
### 3. Health-Checks
**Health-Checks sind kritisch:**
- Container müssen "healthy" werden, sonst starten abhängige Container nicht
- `nginx` wartet auf `app` Health-Check
- `app` wartet auf `redis` Health-Check
**Health-Check Timeouts:**
- `app`: 40s start_period, dann 30s interval
- `redis`: 10s start_period, dann 30s interval
- `nginx`: 10s start_period, dann 30s interval
### 4. Backups
**Backup-Strategie:**
- Jedes Deployment erstellt ein Backup-Verzeichnis
- Enthält: Container-Status, docker-compose.yml, Deployment-Metadaten
- Alte Backups werden automatisch gelöscht (Standard: Behält 5 Backups)
**Backup-Pfad:**
```
~/deployment/backups/
├── 2025-10-31T02-35-04Z/
│ ├── current_containers.json
│ ├── docker-compose-config.yml
│ └── deployment_metadata.txt
├── 2025-10-31T01-20-15Z/
│ └── ...
└── ...
```
---
## Rollback-Prozess
Falls das Deployment fehlschlägt:
### Automatischer Rollback (via Workflow)
```yaml
# Im Workflow: Rollback on failure
if: failure() && steps.health.outcome == 'failure'
run: |
ansible-playbook -i inventory/production.yml \
playbooks/rollback.yml
```
### Manueller Rollback
```bash
cd ~/deployment/ansible
ansible-playbook -i inventory/production.yml \
playbooks/rollback.yml \
-e "rollback_timestamp=2025-10-31T01-20-15Z"
```
**Was passiert beim Rollback:**
1. Liest vorheriges Backup
2. Pullt altes Image
3. Aktualisiert `docker-compose.yml` mit altem Image-Tag
4. Startet Stack neu mit altem Image
---
## Verbesserungsmöglichkeiten
### 1. Blue-Green Deployment
- Zwei parallele Stacks (blue/green)
- Traffic-Switching via Traefik
- Zero-Downtime möglich
### 2. Rolling Updates
- Container werden nacheinander aktualisiert
- Reduzierte Downtime
### 3. Database-Migration vor Deployment
- Migrationen werden aktuell nach Deployment ausgeführt
- Besser: Migrationen vor Deployment testen
### 4. Canary Deployment
- Neue Version zuerst auf Subset der Traffic
- Graduelle Rollout
---
## Troubleshooting
### Container starten nicht
```bash
# Logs prüfen
docker compose -f ~/deployment/stacks/application/docker-compose.yml logs
# Health-Check-Status prüfen
docker compose ps
```
### Image wird nicht gepullt
```bash
# Registry-Login testen
docker login registry.michaelschiemer.de -u admin -p <password>
# Image manuell pullen
docker pull registry.michaelschiemer.de/framework:<tag>
```
### docker-compose.yml wurde nicht aktualisiert
```bash
# Prüfe ob Regex korrekt ist
grep -E "image:\s+registry.michaelschiemer.de/framework" \
~/deployment/stacks/application/docker-compose.yml
# Prüfe Backup für vorherige Version
ls -la ~/deployment/backups/
```
---
## Zusammenfassung
**Deployment-Ablauf:**
1. CI/CD Pipeline baut Image und pusht es zur Registry
2. Ansible Playbook wird auf Production-Server ausgeführt
3. Neues Image wird gepullt
4. `docker-compose.yml` wird mit neuem Image-Tag aktualisiert
5. Application Stack wird mit `--force-recreate` neu gestartet
6. Health-Checks werden ausgeführt
7. Deployment-Metadaten werden gespeichert
8. Workflow führt abschließenden Health-Check aus
**Alle Services erhalten das neue Image:**
- `app` (PHP-FPM)
- `queue-worker` (Queue Worker)
- `scheduler` (Scheduler)
**Zero-Downtime:** Nein, Container werden neu gestartet (kurze Downtime möglich)
**Rollback:** Automatisch via Workflow oder manuell via Rollback-Playbook

186
deployment/docs/reference/workflow-troubleshooting.md Normal file
View File

@@ -0,0 +1,186 @@
# Workflow Troubleshooting Guide
## Problem: Workflows brechen zwischendurch ab
### Mögliche Ursachen
#### 1. Actions werden nicht geladen
**Symptom:** Workflow startet, aber Actions wie `actions/checkout@v4` schlagen fehl
**Lösung:** Prüfe Gitea Konfiguration:
```bash
docker exec gitea cat /data/gitea/conf/app.ini | grep -A 3 '[actions]'
```
Sollte enthalten:
```ini
[actions]
ENABLED = true
# Do NOT set DEFAULT_ACTIONS_URL - it will automatically use Gitea's own instance
# Setting DEFAULT_ACTIONS_URL to custom URLs is no longer supported by Gitea
```
#### 2. Timeouts bei langen Steps
**Symptom:** Workflow läuft eine Zeit, dann Timeout
**Lösung:** Timeout in Runner Config erhöhen:
```yaml
# deployment/gitea-runner/config.yaml
runner:
timeout: 6h # Erhöhe von 3h auf 6h
```
Dann Runner neu starten:
```bash
cd deployment/gitea-runner
docker compose restart gitea-runner
```
#### 3. Docker Buildx Probleme
**Symptom:** Build Step schlägt fehl oder bricht ab
**Lösung:** Prüfe, ob Buildx richtig läuft. Alternativ: Direktes Docker Build verwenden.
#### 4. Gitea-Variablen (früher GitHub-kompatibel)
**Symptom:** `${{ github.sha }}` ist leer oder falsch
**Lösung:** Gitea Actions unterstützt `github.*` Variablen für Kompatibilität, aber `gitea.*` ist die native Variante.
**Test:** Prüfe in Workflow-Logs, welche Variablen verfügbar sind:
```yaml
- name: Debug variables
run: |
echo "GITHUB_SHA: ${{ github.sha }}"
echo "GITEA_SHA: ${{ gitea.sha }}"
echo "RUNNER_OS: ${{ runner.os }}"
```
#### 5. Secrets fehlen oder sind falsch
**Symptom:** Registry Login oder SSH schlägt fehl
**Lösung:** Prüfe Secrets in Gitea:
- Repository → Settings → Secrets
- Alle benötigten Secrets sollten vorhanden sein:
- `REGISTRY_USER`
- `REGISTRY_PASSWORD`
- `SSH_PRIVATE_KEY`
- `ANSIBLE_VAULT_PASSWORD` (falls verwendet)
### Debugging-Schritte
#### 1. Workflow-Logs analysieren
In Gitea UI:
1. Gehe zu Actions → Fehlgeschlagener Workflow
2. Klicke auf fehlgeschlagene Step
3. Prüfe Logs für Fehlermeldungen
4. Suche nach:
- `error`
- `timeout`
- `failed`
- `exit code`
#### 2. Runner-Logs prüfen
```bash
cd deployment/gitea-runner
docker compose logs gitea-runner --tail=100 | grep -E "(error|failed|timeout)"
```
#### 3. Runner Status prüfen
In Gitea: https://git.michaelschiemer.de/admin/actions/runners
Prüfe:
- Status sollte "Idle" oder "Running" sein
- Letzte Aktivität sollte kürzlich sein
- Keine Fehler-Meldungen
### Häufige Fehler und Fixes
#### Problem: "Action not found"
**Fehler:** `Error: Action 'actions/checkout@v4' not found`
**Fix:**
1. Prüfe `DEFAULT_ACTIONS_URL` in Gitea config
2. Stelle sicher, dass Internet-Zugriff vom Runner vorhanden ist
3. Gitea neu starten: `docker compose restart gitea`
#### Problem: "Timeout"
**Fehler:** `timeout: job exceeded maximum duration`
**Fix:**
1. Erhöhe Timeout in `config.yaml`
2. Oder teile Workflow in kleinere Jobs auf
#### Problem: "Docker build failed"
**Fehler:** Docker Build schlägt fehl
**Fix:**
1. Prüfe `docker-dind` Container läuft
2. Prüfe Registry-Zugriff
3. Prüfe Registry-Credentials
#### Problem: "SSH connection failed"
**Fehler:** Ansible Deployment kann nicht zum Server verbinden
**Fix:**
1. Prüfe `SSH_PRIVATE_KEY` Secret ist korrekt
2. Prüfe SSH-Key hat richtige Berechtigungen
3. Prüfe Firewall erlaubt Verbindung
### Workflow optimieren
#### Reduziere Workflow-Zeit
1. **Cache verwenden:**
```yaml
- uses: actions/cache@v3
with:
path: vendor
key: composer-${{ hashFiles('composer.lock') }}
```
2. **Parallel Jobs:**
```yaml
jobs:
test:
# ...
build:
# ...
# Beide können parallel laufen
```
3. **Conditional Steps:**
```yaml
- name: Skip on docs change
if: contains(github.event.head_commit.message, '[skip ci]')
run: exit 0
```
### Nächste Schritte
1. **Identifiziere genaue Abbruch-Stelle:**
- In welchem Step bricht es ab?
- Welche Fehlermeldung erscheint?
2. **Prüfe Logs:**
- Workflow-Logs in Gitea UI
- Runner-Logs: `docker compose logs gitea-runner`
3. **Teste einzelne Steps:**
- Führe Steps manuell aus
- Isoliere das Problem
4. **Workflow vereinfachen:**
- Reduziere auf minimalen Test-Workflow
- Füge Steps schrittweise hinzu

272
deployment/docs/status/ci-cd-status.md Normal file
View File

@@ -0,0 +1,272 @@
# CI/CD Pipeline Status
**Stand:** ✅ CI/CD Pipeline ist vollständig konfiguriert und bereit zum Testen!
## 📖 Dokumentation
- **[Code Changes Workflow](../guides/code-change-workflow.md)** - Anleitung: Wie Codeänderungen gepusht und deployed werden
- **[Application Stack Deployment](../reference/application-stack.md)** - Detaillierte Erklärung des Deployment-Prozesses
## ✅ Was bereits vorhanden ist
### 1. Workflow-Dateien
- ✅ `.gitea/workflows/production-deploy.yml` - Haupt-Deployment-Pipeline
- ✅ `.gitea/workflows/update-production-secrets.yml` - Secrets-Deployment
- ✅ `.gitea/workflows/security-scan.yml` - Security-Vulnerability-Scan
### 2. Gitea Runner Setup
- ✅ `deployment/gitea-runner/docker-compose.yml` - Runner-Konfiguration
- ✅ `deployment/gitea-runner/config.yaml` - Runner-Konfiguration
- ✅ `deployment/gitea-runner/register.sh` - Registration-Script
- ✅ `deployment/gitea-runner/.env.example` - Environment-Template
### 3. Deployment-Scripts
- ✅ `deployment/ansible/playbooks/deploy-update.yml` - Ansible-Deployment
- ✅ `deployment/ansible/playbooks/rollback.yml` - Rollback-Playbook
---
## ⚠️ Was noch fehlt
### 1. Gitea Repository Secrets konfigurieren
**Status**: ✅ Secrets sind bereits konfiguriert
**Konfigurierte Secrets:**
- ✅ `REGISTRY_USER` - Benutzername für Docker Registry
- ✅ `REGISTRY_PASSWORD` - Passwort für Docker Registry
- ✅ `SSH_PRIVATE_KEY` - SSH Private Key für Production-Server-Zugriff
- ⚠️ `GITEA_TOKEN` - Optional: Für automatische Issue-Erstellung bei Security-Scans
**Verifiziert:** Alle kritischen Secrets sind bereits in Gitea konfiguriert.
**Hinweis:** Falls `GITEA_TOKEN` noch nicht konfiguriert ist, kann die automatische Issue-Erstellung bei Security-Scans optional später hinzugefügt werden.
**REGISTRY_USER:**
```
admin
```
**REGISTRY_PASSWORD:**
```
<Das Passwort für registry.michaelschiemer.de>
```
*Zu finden in: `deployment/stacks/registry/auth/htpasswd` oder manuell gesetzt*
**SSH_PRIVATE_KEY:**
```bash
# SSH Key Inhalt anzeigen
cat ~/.ssh/production
```
*Kompletter Inhalt der Datei inkl. `-----BEGIN OPENSSH PRIVATE KEY-----` und `-----END OPENSSH PRIVATE KEY-----`*
**GITEA_TOKEN (optional):**
```
<Gitea Personal Access Token mit repo-Berechtigung>
```
---
### 2. Gitea Runner registrieren und starten
**Status**: ✅ Runner läuft bereits
**Verifiziert:**
- ✅ Runner ist registriert (`data/.runner` existiert)
- ✅ Runner Container läuft (`gitea-runner` ist "Up")
- ✅ Docker-in-Docker Container läuft (`gitea-runner-dind` ist "Up")
- ✅ Runner hat bereits Tasks ausgeführt (task 1-6 in Logs)
- ✅ Runner Name: `dev-runner-01`
- ✅ Runner Labels: `ubuntu-latest`, `ubuntu-22.04`, `debian-latest`
**Hinweis:**
Die Logs zeigen einige Verbindungsfehler (connection refused, 502 Bad Gateway), was normal sein kann wenn Gitea temporär nicht erreichbar ist. Der Runner funktioniert grundsätzlich und hat bereits Tasks erfolgreich ausgeführt.
**Verifizierung in Gitea:**
- Prüfe Runner-Status in Gitea: `https://git.michaelschiemer.de/admin/actions/runners`
- Runner sollte als "Idle" oder "Active" angezeigt werden
---
### 3. Ansible Vault Password Handling
**Status**: ⚠️ Workflow nutzt Vault, aber kein Secret dafür
**Problem:**
- Der Workflow `update-production-secrets.yml` benötigt ein Vault-Passwort
- Aktuell wird es als Workflow-Input eingegeben (manuell)
- Für automatisiertes Deployment sollte es als Secret vorliegen
**Lösung:**
- [ ] Optional: `ANSIBLE_VAULT_PASSWORD` als Secret hinzufügen (nur wenn automatisiert)
- [ ] Oder: Manuelles Eingeben beim Workflow-Trigger ist ausreichend
---
### 4. Pipeline End-to-End testen
**Status**: ⚠️ Pipeline ist definiert, aber noch nicht getestet
**Was fehlt:**
- [ ] Test-Commit pushen und Pipeline-Lauf beobachten
- [ ] Fehler beheben falls notwendig
- [ ] Verifizieren dass Deployment funktioniert
**Test-Schritte:**
1. Stelle sicher dass alle Secrets konfiguriert sind
2. Stelle sicher dass Runner läuft
3. Test-Commit erstellen:
```bash
git checkout -b test/cicd-pipeline
# Kleine Änderung machen
echo "# Test CI/CD" >> README.md
git add README.md
git commit -m "test: CI/CD pipeline"
git push origin test/cicd-pipeline
```
4. Oder: Workflow manuell triggern:
- Gehe zu: `https://git.michaelschiemer.de/michael/michaelschiemer/actions`
- Wähle "Production Deployment Pipeline"
- Klicke "Run workflow"
5. Beobachte Logs und prüfe jeden Schritt:
- ✅ Tests laufen erfolgreich
- ✅ Docker Image wird gebaut
- ✅ Image wird zur Registry gepusht
- ✅ Ansible-Deployment läuft
- ✅ Health-Check schlägt erfolgreich durch
---
## 📋 Checkliste für CI/CD Completion
### Vorbereitung
- [x] Gitea Repository Secrets konfiguriert: ✅
- [x] `REGISTRY_USER` ✅
- [x] `REGISTRY_PASSWORD` ✅
- [x] `SSH_PRIVATE_KEY` ✅
- [ ] `GITEA_TOKEN` (optional)
### Gitea Runner
- [x] Runner Registration Token von Gitea abgerufen ✅
- [x] `deployment/gitea-runner/.env` erstellt und konfiguriert ✅
- [x] Runner registriert ✅
- [x] Runner läuft (`docker compose up -d`) ✅
- [ ] Runner sichtbar in Gitea UI als "Idle" oder "Active" (bitte manuell prüfen)
### Pipeline-Test
- [ ] Test-Commit gepusht oder Workflow manuell getriggert
- [ ] Alle Jobs erfolgreich:
- [ ] Tests
- [ ] Build
- [ ] Deploy
- [ ] Deployment erfolgreich auf Production
- [ ] Health-Check erfolgreich
- [ ] Application läuft korrekt
### Dokumentation
- [ ] Secrets-Setup dokumentiert
- [ ] Runner-Setup dokumentiert
- [ ] Bekannte Probleme/Workarounds dokumentiert
---
## 🎯 Priorisierte Reihenfolge
### Phase 1: Secrets Setup
**Status:** ✅ Abgeschlossen
- Alle kritischen Secrets sind konfiguriert
### Phase 2: Gitea Runner
**Status:** ✅ Abgeschlossen
- Runner läuft und ist registriert
### Phase 3: Pipeline-Test (NÄCHSTER SCHRITT)
**Status:** ⚠️ Ausstehend
1. Test-Workflow ausführen
2. Fehler beheben falls notwendig
3. Production-Deployment verifizieren
---
## 📝 Quick Reference
### Secrets Setup
```bash
# Secrets in Gitea konfigurieren:
https://git.michaelschiemer.de/michael/michaelschiemer/settings/secrets/actions
```
### Runner Setup
```bash
cd deployment/gitea-runner
cp .env.example .env
# Token von https://git.michaelschiemer.de/admin/actions/runners eintragen
./register.sh
docker compose up -d
```
### Pipeline manuell triggern (NÄCHSTER SCHRITT)
```
1. Gehe zu: https://git.michaelschiemer.de/michael/michaelschiemer/actions
2. Wähle: "Production Deployment Pipeline"
3. Klicke: "Run workflow"
4. Wähle Branch: main
5. Optionale Einstellungen:
- skip_tests: false (Tests sollen laufen)
6. Klicke: "Run workflow"
7. Beobachte Logs und prüfe jeden Schritt
```
### Runner-Status prüfen
```
https://git.michaelschiemer.de/admin/actions/runners
```
---
---
## ✅ Aktueller Status
**CI/CD Pipeline ist vollständig konfiguriert!**
- ✅ Secrets konfiguriert
- ✅ Runner läuft und ist registriert
- ✅ Workflows sind vorhanden
- ⚠️ **Nächster Schritt:** Pipeline testen!
**Ready to Deploy:** Die Pipeline kann jetzt getestet werden. Alle Voraussetzungen sind erfüllt.
---
## 🔍 Troubleshooting
### Runner erscheint nicht in Gitea
- Prüfe Runner-Logs: `docker compose logs gitea-runner`
- Prüfe Registration-Token in `.env`
- Re-registrieren: `./unregister.sh && ./register.sh`
### Workflow startet nicht
- Prüfe ob Runner läuft: `docker compose ps`
- Prüfe Runner-Status in Gitea UI
- Prüfe ob Workflow-Datei korrekt ist
### Secrets werden nicht erkannt
- Prüfe Secret-Namen (müssen exakt übereinstimmen)
- Prüfe ob Secrets in korrektem Repository/Organisation sind
- Prüfe ob Secrets nicht abgelaufen sind
### Registry-Login fehlschlägt
- Prüfe `REGISTRY_USER` und `REGISTRY_PASSWORD` Secrets
- Teste Registry-Login manuell:
```bash
docker login registry.michaelschiemer.de -u admin -p <password>
```
### SSH-Verbindung fehlschlägt
- Prüfe `SSH_PRIVATE_KEY` Secret (kompletter Inhalt)
- Prüfe ob Public Key auf Production-Server ist
- Teste SSH-Verbindung manuell:
```bash
ssh -i ~/.ssh/production deploy@94.16.110.151
```

188
deployment/docs/status/deployment-summary.md Normal file
View File

@@ -0,0 +1,188 @@
# Deployment Projekt - Zusammenfassung
**Stand:** 2025-10-31
**Status:** ✅ CI/CD Pipeline vollständig konfiguriert und bereit zum Testen
---
## ✅ Was ist fertig?
### Infrastructure (100% abgeschlossen)
- ✅ **Traefik** - Reverse Proxy & SSL (Stack 1)
- ✅ **PostgreSQL** - Database mit automatischen Backups (Stack 2)
- ✅ **Docker Registry** - Private Registry (Stack 3)
- ✅ **Gitea** - Git Server mit CI/CD (Stack 4)
- ✅ **Monitoring** - Portainer, Grafana, Prometheus (Stack 6)
- ✅ **WireGuard VPN** - VPN-Server Setup mit Ansible
### Application Stack (100% abgeschlossen)
- ✅ **Application Stack Integration** - In `setup-infrastructure.yml` integriert
- ✅ **Environment Template** - `application.env.j2` für automatische Konfiguration
- ✅ **Database Migration** - Automatisch nach Deployment
- ✅ **Health-Checks** - Integration nach Deployment
- ✅ **PostgreSQL Integration** - Verwendet PostgreSQL statt MySQL
### CI/CD Pipeline (100% konfiguriert)
- ✅ **Workflows** - Production-Deploy, Secrets-Update, Security-Scan
- ✅ **Gitea Runner** - Läuft und ist registriert
- ✅ **Secrets** - Alle kritischen Secrets konfiguriert
- ✅ **Ansible Integration** - Deployment & Rollback Playbooks
- ✅ **Dokumentation** - Umfangreiche Guides vorhanden
### Dokumentation (95% abgeschlossen)
- ✅ `CODE_CHANGE_WORKFLOW.md` - Codeänderungen pushen
- ✅ `APPLICATION_STACK_DEPLOYMENT.md` - Deployment-Ablauf
- ✅ `CI_CD_STATUS.md` - CI/CD Status & Checkliste
- ✅ `QUICK_START.md` - Schnellstart-Guide
- ✅ `README.md` - Haupt-Dokumentation aktualisiert
- ✅ WireGuard Dokumentation
- ⚠️ `DEPLOYMENT-STATUS.md` - Sollte final aktualisiert werden
---
## ⚠️ Was fehlt noch?
### 1. Pipeline End-to-End testen (KRITISCH)
**Status:** ⚠️ Ausstehend
**Was zu tun:**
- [ ] Test-Commit pushen oder Workflow manuell triggern
- [ ] Alle Jobs verifizieren (Tests, Build, Deploy)
- [ ] Deployment auf Production verifizieren
- [ ] Health-Check erfolgreich
- [ ] Fehler beheben falls notwendig
**Zeit:** ~15-30 Minuten
**Schritte:**
```bash
# Option 1: Test-Commit
echo "# Test" >> README.md
git add README.md
git commit -m "test: CI/CD pipeline test"
git push origin main
# Option 2: Manuell triggern
# → https://git.michaelschiemer.de/michael/michaelschiemer/actions
# → "Production Deployment Pipeline" → "Run workflow"
```
### 2. Backup-Playbook erstellen (Optional)
**Status:** ⚠️ Ausstehend
**Was zu tun:**
- [ ] Backup-Playbook für Application Stack erstellen
- [ ] PostgreSQL Backup-Integration
- [ ] Gitea Data Backup
- [ ] Registry Images Backup
**Dateien:**
- `deployment/ansible/playbooks/backup.yml` ❌ Fehlt
- `deployment/ansible/playbooks/rollback.yml` ✅ Vorhanden
### 3. Finale Dokumentation (Optional)
**Status:** ⚠️ Teilweise
**Was zu tun:**
- [ ] `DEPLOYMENT-STATUS.md` mit finalem Status aktualisieren
- [ ] `SETUP-GUIDE.md` finalisieren (optional)
---
## 📚 Dokumentation Übersicht
### Quick Start
- **`QUICK_START.md`** - Schnellstart-Guide für Deployment
- **`CODE_CHANGE_WORKFLOW.md`** - Wie Codeänderungen gepusht werden
### Detaillierte Guides
- **`APPLICATION_STACK_DEPLOYMENT.md`** - Detaillierter Deployment-Ablauf
- **`CI_CD_STATUS.md`** - CI/CD Pipeline Status & Checkliste
- **`SETUP-GUIDE.md`** - Kompletter Setup-Guide
- **`DEPLOYMENT-TODO.md`** - Aktuelle TODO-Liste
### Stack-Dokumentation
- **`stacks/application/README.md`** - Application Stack Details
- **`ansible/README.md`** - Ansible Playbooks Dokumentation
- **`gitea-runner/README.md`** - Gitea Runner Setup
---
## 🎯 Nächste Schritte (Priorisiert)
### 1. Pipeline testen (KRITISCH - Nächster Schritt)
```bash
# Test-Commit pushen
echo "# Test" >> README.md
git add README.md
git commit -m "test: CI/CD pipeline test"
git push origin main
# Pipeline beobachten
# → https://git.michaelschiemer.de/michael/michaelschiemer/actions
```
**Erfolgskriterien:**
- ✅ Alle Jobs erfolgreich (Tests, Build, Deploy)
- ✅ Deployment auf Production erfolgreich
- ✅ Health-Check erfolgreich
- ✅ Application läuft korrekt
### 2. Backup-Playbook erstellen (Optional)
```bash
cd deployment/ansible/playbooks
# Erstelle backup.yml
```
### 3. Finale Verifikation (Optional)
- Alles nochmal durchgehen
- Dokumentation finalisieren
- Eventuelle Verbesserungen identifizieren
---
## 📊 Projekt-Status
### Completion Rate
- **Infrastructure:** 100% ✅
- **Application Stack:** 100% ✅
- **CI/CD Pipeline:** 100% konfiguriert ✅
- **Dokumentation:** 95% ✅
- **Testing:** 0% ⚠️ (nächster Schritt!)
### Gesamt: ~95% abgeschlossen
**Nächster kritischer Schritt:** Pipeline testen!
---
## 🚀 Ready to Deploy!
**Alles ist bereit für das erste Deployment!**
Die CI/CD Pipeline ist vollständig konfiguriert:
- ✅ Secrets konfiguriert
- ✅ Runner läuft
- ✅ Workflows vorhanden
- ✅ Ansible Playbooks vorhanden
- ✅ Dokumentation vorhanden
**Nächster Schritt:** Einfach einen Test-Commit pushen oder Workflow manuell triggern!
---
**Viel Erfolg beim ersten Deployment!** 🎉

292
deployment/docs/status/deployment-todo.md Normal file
View File

@@ -0,0 +1,292 @@
# Deployment TODO - Komplette Implementierung
**Status**: ✅ ~95% Abgeschlossen - Ready for Testing
**Letzte Aktualisierung**: 2025-10-31
**Ziel**: Komplettes Deployment-Setup im `deployment/` Ordner
**🎯 Nächster kritischer Schritt:** Pipeline End-to-End testen!
---
## ✅ Bereits Fertig
### Infrastructure Stacks (deployed via Ansible)
- ✅ **Traefik** - Reverse Proxy & SSL
- ✅ **PostgreSQL** - Database Stack
- ✅ **Docker Registry** - Private Registry
- ✅ **Gitea** - Git Server + MySQL + Redis
- ✅ **Monitoring** - Portainer + Grafana + Prometheus
- ✅ **WireGuard VPN** - VPN Server
### Ansible Playbooks
- ✅ `setup-infrastructure.yml` - Infrastructure Stacks Deployment
- ✅ `setup-wireguard.yml` - WireGuard VPN Setup
- ✅ `add-wireguard-client.yml` - WireGuard Client hinzufügen
- ✅ `deploy-update.yml` - Application Update Deployment
- ✅ `rollback.yml` - Rollback zu vorheriger Version
- ✅ `setup-production-secrets.yml` - Secrets Deployment
- ✅ `setup-ssl-certificates.yml` - SSL Certificate Setup
- ✅ `sync-stacks.yml` - Stacks synchronisieren
### Dokumentation
- ✅ `README.md` - Deployment Übersicht
- ✅ `SETUP-GUIDE.md` - Komplette Setup-Anleitung
- ✅ `DEPLOYMENT-STATUS.md` - Aktueller Status
- ✅ `docs/WIREGUARD-SETUP.md` - WireGuard Dokumentation
---
## ⏳ Offene Aufgaben
### 1. Application Stack Integration
**Status**: ⚠️ Fehlt in `setup-infrastructure.yml`
**Was fehlt:**
- [x] Application Stack zu `setup-infrastructure.yml` hinzufügen ✅
- [x] `.env` Template für Application Stack erstellen (`application.env.j2`) ✅
- [x] Ansible Playbook/Task für Application Stack Deployment ✅
- [x] Database-Migration nach Application Deployment ✅
- [x] Health-Check nach Application Deployment ✅
**Dateien:**
- `deployment/stacks/application/docker-compose.yml` ✅ Vorhanden
- `deployment/stacks/application/.env.example` ✅ Vorhanden
- `deployment/stacks/application/.env` ❌ Fehlt (muss generiert werden)
- `deployment/ansible/templates/application.env.j2` ❌ Fehlt (Template für `.env`)
- `deployment/ansible/playbooks/setup-infrastructure.yml` ⚠️ Application fehlt
**Nächste Schritte:**
1. Application Stack Deployment Task zu `setup-infrastructure.yml` hinzufügen
2. `.env` Template erstellen (mit Passwörtern aus Vault)
3. Database-Migration nach Application Start
4. Health-Check Integration
---
### 2. Application Stack .env Konfiguration
**Status**: ✅ Erledigt
**Was erledigt:**
- [x] Ansible Template für `.env` Datei erstellt (`application.env.j2`) ✅
- [x] Passwörter aus Vault/PostgreSQL .env laden ✅
- [x] Domain-Konfiguration aus Inventory ✅
- [x] Environment-Variablen aus Vault/Template generieren ✅
**Dateien:**
- `deployment/stacks/application/.env.example` ✅ Vorhanden (angepasst für PostgreSQL)
- `deployment/stacks/application/.env` ⚠️ Wird automatisch generiert
- `deployment/ansible/templates/application.env.j2` ✅ Erstellt
- `deployment/stacks/application/docker-compose.yml` ✅ Angepasst (PostgreSQL statt MySQL)
---
### 3. Gitea Runner Setup abschließen
**Status**: ⏳ Wartet auf Registration Token
**Was fehlt:**
- [ ] Gitea Admin Panel öffnen: https://git.michaelschiemer.de/admin/actions/runners
- [ ] Actions in Gitea aktivieren (falls noch nicht geschehen)
- [ ] Registration Token abrufen
- [ ] Token in `.env` eintragen
- [ ] Runner registrieren und starten
**Dateien:**
- `deployment/gitea-runner/.env` ⚠️ Vorhanden, aber Token fehlt
- `deployment/gitea-runner/.env.example` ✅ Vorhanden
**Nächste Schritte:**
1. Gitea Actions aktivieren (Admin Panel)
2. Runner Registration Token generieren
3. Token in `.env` eintragen
4. Runner starten: `cd deployment/gitea-runner && docker compose up -d`
---
### 4. CI/CD Pipeline finalisieren
**Status**: ✅ Vollständig konfiguriert - Bereit zum Testen
**Was fehlt:**
- [x] **Gitea Repository Secrets konfigurieren:** ✅
- [x] `REGISTRY_USER` (Docker Registry Benutzername) ✅
- [x] `REGISTRY_PASSWORD` (Docker Registry Passwort) ✅
- [x] `SSH_PRIVATE_KEY` (SSH Private Key für Production-Server) ✅
- [ ] `GITEA_TOKEN` (Optional: Für automatische Issue-Erstellung)
- [x] **Gitea Runner registrieren:** ✅
- [x] Registration Token von Gitea Admin Panel abgerufen ✅
- [x] Token in `deployment/gitea-runner/.env` eingetragen ✅
- [x] Runner registriert ✅
- [x] Runner läuft ✅
- [ ] **Pipeline End-to-End testen:**
- [ ] Test-Commit pushen oder Workflow manuell triggern
- [ ] Alle Jobs erfolgreich (Tests, Build, Deploy)
- [ ] Deployment erfolgreich auf Production
- [ ] Health-Check erfolgreich
**Dateien:**
- `.gitea/workflows/production-deploy.yml` ✅ Vorhanden
- `.gitea/workflows/update-production-secrets.yml` ✅ Vorhanden
- `.gitea/workflows/security-scan.yml` ✅ Vorhanden
- `deployment/CI_CD_STATUS.md` ✅ Neu erstellt (detaillierte Checkliste)
**Detaillierte Anleitung:**
Siehe `deployment/CI_CD_STATUS.md` für komplette Checkliste und Setup-Anleitung.
**Nächste Schritte:**
1. **Secrets in Gitea konfigurieren:**
- Gehe zu: `https://git.michaelschiemer.de/michael/michaelschiemer/settings/secrets/actions`
- Füge Secrets hinzu: `REGISTRY_USER`, `REGISTRY_PASSWORD`, `SSH_PRIVATE_KEY`
2. **Gitea Runner registrieren:**
- Token von: `https://git.michaelschiemer.de/admin/actions/runners`
- Konfiguriere `deployment/gitea-runner/.env`
- Führe `./register.sh` aus
3. **Pipeline testen:**
- Workflow manuell triggern oder Test-Commit pushen
- Logs beobachten und Fehler beheben
---
### 5. Backup & Rollback Scripts
**Status**: ⚠️ Teilweise vorhanden
**Was fehlt:**
- [ ] Backup-Playbook für Application Stack
- [ ] Rollback-Playbook testen und finalisieren
- [ ] PostgreSQL Backup-Integration
- [ ] Gitea Data Backup
- [ ] Registry Images Backup
**Dateien:**
- `deployment/ansible/playbooks/rollback.yml` ✅ Vorhanden
- `deployment/stacks/postgresql/scripts/backup.sh` ✅ Vorhanden
- `deployment/ansible/playbooks/backup.yml` ❌ Fehlt
**Nächste Schritte:**
1. Backup-Playbook erstellen
2. Rollback-Playbook testen
3. Backup-Scripte finalisieren
4. Automatisierte Backups konfigurieren
---
### 6. Deployment Automation (Erledigt ✅)
**Status**: ✅ Abgeschlossen
**Was erledigt:**
- [x] Alle Deployment-Operationen über Ansible Playbooks ✅
- [x] Redundante Scripts entfernt ✅
- [x] Dokumentation aktualisiert ✅
**Dateien:**
- `deployment/ansible/playbooks/deploy-update.yml` ✅ Vorhanden
- `deployment/ansible/playbooks/rollback.yml` ✅ Vorhanden
- `deployment/ansible/playbooks/sync-code.yml` ✅ Vorhanden
- `deployment/DEPLOYMENT_COMMANDS.md` ✅ Command-Referenz erstellt
**Alle Deployment-Operationen werden jetzt direkt über Ansible durchgeführt:**
```bash
cd deployment/ansible
ansible-playbook -i inventory/production.yml playbooks/<playbook>.yml
```
---
### 7. Dokumentation vervollständigen
**Status**: ⚠️ Gut, aber einige Updates nötig
**Was fehlt:**
- [ ] `DEPLOYMENT-STATUS.md` aktualisieren (Application Stack Status)
- [ ] `README.md` aktualisieren (Application Stack Deployment)
- [ ] `SETUP-GUIDE.md` aktualisieren (Application Stack Phase)
- [ ] Troubleshooting Guide für Application Stack
**Dateien:**
- `deployment/README.md` ⚠️ Muss aktualisiert werden
- `deployment/SETUP-GUIDE.md` ⚠️ Muss aktualisiert werden
- `deployment/DEPLOYMENT-STATUS.md` ⚠️ Muss aktualisiert werden
---
## 🎯 Priorisierte Reihenfolge
### ✅ Phase 1: Application Stack Deployment - ABGESCHLOSSEN
1. ✅ **Application Stack zu setup-infrastructure.yml hinzufügen**
- ✅ Task für Application Stack Deployment
- ✅ `.env` Template erstellt (`application.env.j2`)
- ✅ Database-Migration nach Deployment
2. ✅ **Application .env Konfiguration**
- ✅ Template `application.env.j2` erstellt
- ✅ Passwörter aus Vault/PostgreSQL .env laden
- ✅ Template in Playbook integriert
### ✅ Phase 2: CI/CD Setup - ABGESCHLOSSEN
3. ✅ **Gitea Runner Setup abschließen**
- ✅ Token konfiguriert
- ✅ Runner läuft und ist registriert
4. ✅ **CI/CD Pipeline finalisieren**
- ✅ Secrets in Gitea konfiguriert
- ⚠️ **Pipeline testen** - NÄCHSTER SCHRITT
### ⚠️ Phase 3: Testing & Finalisierung (NÄCHSTER SCHRITT)
5. **Pipeline End-to-End testen** ⚠️ **KRITISCH**
- Test-Commit pushen oder Workflow manuell triggern
- Alle Jobs verifizieren (Tests, Build, Deploy)
- Deployment auf Production verifizieren
- Health-Check erfolgreich
- Fehler beheben falls notwendig
### Phase 3: Backup & Scripts
5. **Backup & Rollback Scripts**
- Backup-Playbook erstellen
- Rollback testen
6. **Deployment Scripts finalisieren**
- Scripts testen und anpassen
### Phase 4: Dokumentation
7. **Dokumentation aktualisieren**
- README aktualisieren
- Status-Dokumente aktualisieren
---
## 📋 Quick Checklist
### Application Stack
- [x] Application Stack in `setup-infrastructure.yml` hinzufügen ✅
- [x] `.env` Template (`application.env.j2`) erstellen ✅
- [x] Database-Migration Task hinzufügen ✅
- [x] Health-Check nach Deployment ✅
### CI/CD
- [x] Gitea Runner Token konfigurieren ✅
- [x] Runner starten ✅
- [x] Secrets in Gitea konfigurieren ✅
- [ ] Pipeline testen ⚠️ **NÄCHSTER SCHRITT**
### Scripts & Backup
- [ ] Backup-Playbook erstellen
- [ ] Rollback testen
- [ ] Deployment-Scripts finalisieren
### Dokumentation
- [ ] README aktualisieren
- [ ] SETUP-GUIDE aktualisieren
- [ ] DEPLOYMENT-STATUS aktualisieren
---
**Nächster Schritt**: Application Stack zu `setup-infrastructure.yml` hinzufügen und `.env` Template erstellen

260
deployment/docs/status/improvements.md Normal file
View File

@@ -0,0 +1,260 @@
# Deployment System - Verbesserungsvorschläge
**Erstellt:** 2025-01-31
**Status:** Vorschläge zur Diskussion
---
## 🔍 Gefundene Redundanzen und Verbesserungsmöglichkeiten
### 1. ❌ **Dokumentations-Redundanz**
#### Problem:
- **38+ Markdown-Dateien** im `deployment/` und `docs/deployment/` Verzeichnis
- Viele veraltete Dokumentationsdateien in `docs/deployment/`
- Überschneidende Inhalte zwischen mehreren Dateien
#### Konkrete Redundanzen:
- `DEPLOYMENT_SUMMARY.md` vs `DEPLOYMENT-TODO.md` (ähnliche Status-Übersichten)
- `NATIVE-WORKFLOW-README.md` (veraltet? bereits durch CI/CD Pipeline ersetzt)
- `docs/deployment/*` - Viele veraltete Guides (Swarm, alte Workflows, etc.)
#### Empfehlung:
```bash
# Dateien die gelöscht/archiviert werden könnten:
- deployment/NATIVE-WORKFLOW-README.md # Durch CI/CD Pipeline ersetzt
- docs/deployment/docker-swarm-deployment.md # Swarm nicht mehr verwendet
- docs/deployment/DEPLOYMENT_RESTRUCTURE.md # Historisch
- docs/deployment/* (viele veraltete Dateien)
```
**Lösung:**
- Dokumentation konsolidieren auf:
- `README.md` - Haupt-Dokumentation
- `QUICK_START.md` - Schnellstart
- `DEPLOYMENT_COMMANDS.md` - Command-Referenz
- `CODE_CHANGE_WORKFLOW.md` - Workflow-Dokumentation
- `SETUP-GUIDE.md` - Setup-Anleitung
- Stack-spezifische READMEs in `stacks/*/README.md`
---
### 2. ❌ **Playbook-Redundanz: Troubleshooting Playbooks**
#### Problem:
4 separate Playbooks für ähnliche Troubleshooting-Aufgaben:
- `check-container-health.yml` - Prüft Health Status
- `diagnose-404.yml` - Diagnostiziert 404 Fehler
- `fix-container-health-checks.yml` - Fixes Health Checks
- `fix-nginx-404.yml` - Fixes Nginx 404
#### Empfehlung:
**Konsolidieren zu einem einzigen Playbook** `troubleshoot.yml` mit Tags:
```yaml
# deployment/ansible/playbooks/troubleshoot.yml
---
- name: Application Troubleshooting
hosts: production
gather_facts: yes
become: no
tasks:
- name: Check container health
include_tasks: tasks/check-health.yml
tags: ['health', 'check']
- name: Diagnose 404 errors
include_tasks: tasks/diagnose-404.yml
tags: ['404', 'diagnose']
- name: Fix container health checks
include_tasks: tasks/fix-health-checks.yml
tags: ['health', 'fix']
- name: Fix nginx 404
include_tasks: tasks/fix-nginx-404.yml
tags: ['nginx', '404', 'fix']
```
**Verwendung:**
```bash
# Nur Diagnose
ansible-playbook ... troubleshoot.yml --tags diagnose
# Nur Fix
ansible-playbook ... troubleshoot.yml --tags fix
# Alles
ansible-playbook ... troubleshoot.yml
```
**Vorteile:**
- Weniger Redundanz
- Einfacher zu warten
- Konsistente Struktur
---
### 3. ⚠️ **Variablen-Redundanz**
#### Problem:
Jedes Playbook definiert eigene Pfade:
```yaml
# In vielen Playbooks:
vars:
app_stack_path: "{{ deploy_user_home }}/deployment/stacks/application"
stacks_base_path: "~/deployment/stacks"
```
#### Empfehlung:
**Zentrale Variablendefinition** in `group_vars/production.yml`:
```yaml
# deployment/ansible/group_vars/production.yml
---
# Base paths
deploy_user_home: "~"
stacks_base_path: "{{ deploy_user_home }}/deployment/stacks"
app_stack_path: "{{ stacks_base_path }}/application"
backups_path: "{{ deploy_user_home }}/deployment/backups"
# Registry
docker_registry_url: "registry.michaelschiemer.de"
app_image: "{{ docker_registry_url }}/framework"
app_name: "framework"
# Health checks
health_check_url: "https://michaelschiemer.de/health"
max_rollback_versions: 5
```
**Vorteile:**
- Einmal definiert, überall verwendbar
- Einfacher zu ändern
- Konsistenz über alle Playbooks
---
### 4. ❓ **Playbook: `sync-stacks.yml`**
#### Problem:
`sync-stacks.yml` synchronisiert Stack-Dateien zu Production, aber:
- `setup-infrastructure.yml` deployed die Stacks bereits direkt
- Wird wahrscheinlich nicht mehr benötigt?
#### Empfehlung:
**Entweder:**
1. **Löschen** wenn nicht mehr verwendet
2. **Oder dokumentieren** wann es noch gebraucht wird
---
### 5. ❓ **Stack-Redundanz: `postgres/` vs `postgresql/`**
#### Problem:
Es gibt beide Ordner:
- `deployment/stacks/postgres/`
- `deployment/stacks/postgresql/`
Einer scheint leer zu sein?
#### Empfehlung:
- Prüfen welcher verwendet wird
- Leeren Ordner löschen
- Konsistente Namensgebung verwenden
---
### 6. ✅ **Playbook: WireGuard Dokumentation**
#### Positiv:
WireGuard hat separate README (`README-WIREGUARD.md`) - das ist gut strukturiert!
**Könnte als Vorbild dienen** für andere komplexe Features.
---
### 7. ⚠️ **Templates: Mehrfache .env Templates**
#### Problem:
- `ansible/templates/application.env.j2`
- `ansible/templates/monitoring.env.j2`
- Gibt es weitere?
#### Empfehlung:
**Template-Verzeichnis strukturieren:**
```
ansible/templates/
├── env/
│ ├── application.env.j2
│ ├── monitoring.env.j2
│ └── ...
└── config/
├── wireguard-server.conf.j2
└── ...
```
---
### 8. ✅ **Verbesserung: Zentrales Playbook für Common Tasks**
#### Empfehlung:
**Common Tasks als Reusable Roles/Tasks**:
```yaml
# deployment/ansible/roles/common/tasks/verify-stack.yml
---
- name: Verify stack directory exists
stat:
path: "{{ stack_path }}"
register: stack_dir
- name: Fail if stack directory doesn't exist
fail:
msg: "Stack directory not found at {{ stack_path }}"
when: not stack_dir.stat.exists
```
**Verwendung in Playbooks:**
```yaml
- name: Verify application stack
include_role:
name: common
tasks_from: verify-stack
vars:
stack_path: "{{ app_stack_path }}"
```
**Vorteile:**
- DRY (Don't Repeat Yourself)
- Konsistenz
- Einfacher zu warten
---
## 📊 Priorisierte Empfehlungen
### 🔴 Hoch (sofort umsetzbar):
1. **Zentrale Variablen** → `group_vars/production.yml`
2. **Dokumentation aufräumen** → Veraltete Dateien löschen/archivieren
3. **Stack-Redundanz prüfen** → `postgres/` vs `postgresql/`
### 🟡 Mittel (bald umsetzen):
4. **Troubleshooting Playbooks konsolidieren** → Ein Playbook mit Tags
5. **Common Tasks als Roles** → Redundanz reduzieren
### 🟢 Niedrig (nice to have):
6. **Template-Struktur verbessern**
7. **Playbook `sync-stacks.yml` prüfen** → Ob noch benötigt
---
## 📝 Nächste Schritte
1. ✅ Redundante Scripts entfernt
2. ⏳ Dokumentation aufräumen
3. ⏳ Zentrale Variablen erstellen
4. ⏳ Troubleshooting Playbooks konsolidieren
**Soll ich mit der Umsetzung beginnen?**

48
deployment/docs/status/next-steps.md Normal file
View File

@@ -0,0 +1,48 @@
# Git Deployment - Nächste Schritte
## ✅ Was funktioniert:
- Git-Variablen in `.env` gesetzt ✅
- Ansible Playbook funktioniert ✅
- Container neu gestartet ✅
## ❌ Was noch fehlt:
- **Image enthält noch alte Version** ohne Git-Funktionalität
- Environment-Variablen werden nicht geladen
## 🔧 Lösung:
### Option 1: Image lokal pushen (Schnell)
```bash
# Im Projekt-Root
docker push registry.michaelschiemer.de/framework:latest
```
Dann Container neu starten:
```bash
cd deployment/ansible
ansible-playbook -i inventory/production.yml playbooks/sync-code.yml \
-e "git_repo_url=https://git.michaelschiemer.de/michael/michaelschiemer.git" \
-e "git_branch=main"
```
### Option 2: Via CI/CD (Empfohlen für Production)
1. **Commit und Push** deiner Änderungen
2. **CI/CD Pipeline** baut automatisch das Image
3. **Dann** `sync-code.yml` ausführen
---
## 📊 Zusammenfassung
**Status:** Setup abgeschlossen, Image muss aktualisiert werden
**Alle Komponenten sind bereit:**
- ✅ Entrypoint Script mit Git-Funktionalität
- ✅ Dockerfile mit Git + Composer
- ✅ Docker Compose mit Git Environment Variables
- ✅ Ansible Playbook für Git-Sync
- ✅ .env mit Git-Variablen
**Nur noch:** Image pushen und Container neu starten!

73
deployment/docs/tests/git-deployment-issue.md Normal file
View File

@@ -0,0 +1,73 @@
# Git Deployment - Problem gefunden
**Datum:** 2025-01-31
**Status:** ⚠️ Image muss neu gepusht werden
## 🔍 Problem identifiziert
### Prüfung ergab:
- ❌ Keine Git-Logs im Container
- ❌ `GIT_REPOSITORY_URL` nicht als Environment-Variable gesetzt
- ❌ Kein `.git` Verzeichnis im Container
- ❌ Entrypoint-Script zeigt keine Git-Funktionalität
### Ursache:
**Das Image auf dem Production-Server enthält noch die alte Version ohne Git-Funktionalität.**
Das lokal gebaute Image wurde noch nicht zur Registry gepusht, daher verwendet der Production-Server noch das alte Image.
---
## ✅ Lösung
### Schritt 1: Image zur Registry pushen
```bash
# Lokal (auf Dev-Machine)
docker push registry.michaelschiemer.de/framework:latest
```
### Schritt 2: Image auf Production-Server aktualisieren
```bash
# Via Ansible
cd deployment/ansible
ansible production -i inventory/production.yml -m shell -a "docker pull registry.michaelschiemer.de/framework:latest"
```
### Schritt 3: Container neu starten
```bash
# Via Ansible
cd deployment/ansible
ansible-playbook -i inventory/production.yml playbooks/sync-code.yml -e "git_repo_url=https://git.michaelschiemer.de/michael/michaelschiemer.git" -e "git_branch=main"
```
**Oder direkt:**
```bash
# Auf Production-Server
cd ~/deployment/stacks/application
docker compose pull app
docker compose up -d app
```
---
## 🔄 Alternativer Workflow
Falls du das Image über die CI/CD Pipeline pushen möchtest:
1. **Commit und Push** der Änderungen zu `main`
2. **CI/CD Pipeline** baut automatisch das Image und pusht es
3. **Dann** `sync-code.yml` ausführen
---
## 📋 Checkliste
- [ ] Image lokal gebaut ✅
- [ ] Git-Variablen in .env gesetzt ✅
- [ ] Image zur Registry pushen ❌ **TODO**
- [ ] Image auf Production-Server pullen ❌ **TODO**
- [ ] Container neu starten ❌ **TODO**
- [ ] Logs prüfen ❌ **TODO**

239
deployment/docs/tests/git-deployment-test.md Normal file
View File

@@ -0,0 +1,239 @@
# Git-basiertes Deployment - Test Plan
**Datum:** 2025-01-31
**Status:** ⏳ Ready to Test
---
## 🎯 Ziel
Testen, ob Container automatisch Code aus Git-Repository klont/pullt beim Start.
---
## ✅ Vorbereitung
### 1. Prüfen ob alles korrekt konfiguriert ist
#### Docker Entrypoint
- ✅ `docker/entrypoint.sh` - Git Clone/Pull implementiert
- ✅ `Dockerfile.production` - Git + Composer installiert
#### Docker Compose
- ✅ `deployment/stacks/application/docker-compose.yml` - Git Environment Variables vorhanden
#### Ansible Playbook
- ✅ `deployment/ansible/playbooks/sync-code.yml` - Erstellt
---
## 🧪 Test-Plan
### Test 1: Git-Variablen in .env setzen
**Ziel:** Prüfen ob Git-Konfiguration in .env gesetzt werden kann
```bash
# SSH zum Production-Server
ssh deploy@94.16.110.151
# Prüfen ob .env existiert
cd ~/deployment/stacks/application
test -f .env && echo "✅ OK" || echo "❌ Fehlt"
# Git-Variablen manuell hinzufügen (für Test)
cat >> .env << 'EOF'
# Git Repository Configuration
GIT_REPOSITORY_URL=https://git.michaelschiemer.de/michael/michaelschiemer.git
GIT_BRANCH=main
GIT_TOKEN=
EOF
```
**Erwartetes Ergebnis:**
- ✅ .env existiert
- ✅ Git-Variablen können hinzugefügt werden
---
### Test 2: Container mit Git-Variablen starten
**Ziel:** Prüfen ob Container Git Clone/Pull beim Start ausführt
```bash
# Auf Production-Server
cd ~/deployment/stacks/application
# Container neu starten
docker compose restart app
# Logs prüfen (sollte Git Clone/Pull zeigen)
docker logs app --tail 100 | grep -E "(Git|Clone|Pull|✅|❌)"
```
**Erwartetes Ergebnis:**
- ✅ Logs zeigen "📥 Cloning/Pulling code from Git repository..."
- ✅ Logs zeigen "📥 Cloning repository from ..." oder "🔄 Pulling latest changes..."
- ✅ Logs zeigen "✅ Git sync completed"
**Falls Fehler:**
- ❌ Logs zeigen Fehler → Troubleshooting nötig
- ❌ Keine Git-Logs → Entrypoint nicht korrekt oder Git-Variablen nicht gesetzt
---
### Test 3: Code-Verifikation im Container
**Ziel:** Prüfen ob Code tatsächlich im Container ist
```bash
# Auf Production-Server
docker exec app ls -la /var/www/html/ | head -20
docker exec app test -f /var/www/html/composer.json && echo "✅ composer.json vorhanden" || echo "❌ Fehlt"
docker exec app test -d /var/www/html/src && echo "✅ src/ vorhanden" || echo "❌ Fehlt"
docker exec app test -d /var/www/html/.git && echo "✅ .git vorhanden" || echo "❌ Fehlt"
```
**Erwartetes Ergebnis:**
- ✅ Dateien sind im Container
- ✅ `.git` Verzeichnis existiert (zeigt dass Git Clone funktioniert hat)
---
### Test 4: Code-Update testen (Git Pull)
**Ziel:** Prüfen ob `sync-code.yml` Playbook funktioniert
```bash
# Lokal (auf Dev-Machine)
cd deployment/ansible
# Sync-Code Playbook ausführen
ansible-playbook -i inventory/production.yml \
playbooks/sync-code.yml \
-e "git_branch=main"
# Container-Logs prüfen (auf Production-Server)
ssh deploy@94.16.110.151
docker logs app --tail 50 | grep -E "(Git|Pull|✅)"
```
**Erwartetes Ergebnis:**
- ✅ Playbook führt erfolgreich aus
- ✅ Container wird neu gestartet
- ✅ Logs zeigen "🔄 Pulling latest changes..."
- ✅ Code wird aktualisiert
---
### Test 5: Application Health Check
**Ziel:** Prüfen ob Application nach Git-Sync noch funktioniert
```bash
# Health Check
curl -f https://michaelschiemer.de/health || echo "❌ Health Check fehlgeschlagen"
# Application Test
curl -f https://michaelschiemer.de/ || echo "❌ Application fehlgeschlagen"
```
**Erwartetes Ergebnis:**
- ✅ Health Check erfolgreich
- ✅ Application läuft
---
## 🔧 Troubleshooting
### Problem: Container zeigt keine Git-Logs
**Mögliche Ursachen:**
1. `GIT_REPOSITORY_URL` nicht in .env gesetzt
2. Entrypoint Script nicht korrekt
3. Git nicht im Container installiert
**Lösung:**
```bash
# Prüfen .env
cd ~/deployment/stacks/application
grep GIT_REPOSITORY_URL .env
# Prüfen Entrypoint
docker exec app cat /usr/local/bin/entrypoint.sh | grep -A 10 "GIT_REPOSITORY_URL"
# Prüfen Git Installation
docker exec app which git
docker exec app git --version
```
---
### Problem: Git Clone fehlgeschlagen
**Mögliche Ursachen:**
1. Repository nicht erreichbar vom Server
2. Falsche Credentials
3. Branch nicht existiert
**Lösung:**
```bash
# Prüfen Repository-Zugriff
docker exec app git clone --branch main --depth 1 https://git.michaelschiemer.de/michael/michaelschiemer.git /tmp/test-clone
# Logs prüfen
docker logs app --tail 100 | grep -i "error\|fail"
```
---
### Problem: Composer Install fehlgeschlagen
**Mögliche Ursachen:**
1. Composer nicht installiert
2. Network-Probleme beim Dependency-Download
**Lösung:**
```bash
# Composer prüfen
docker exec app which composer
docker exec app composer --version
# Manuell testen
docker exec app sh -c "cd /var/www/html && composer install --no-dev --optimize-autoloader --no-interaction"
```
---
## 📋 Checkliste für Test
### Vor Test:
- [ ] Git-Repository ist erreichbar vom Production-Server
- [ ] Git-Credentials sind verfügbar (falls private Repository)
- [ ] .env Datei existiert auf Production-Server
- [ ] Container-Image wurde neu gebaut (mit Git + Composer)
### Während Test:
- [ ] Test 1: Git-Variablen in .env setzen
- [ ] Test 2: Container mit Git-Variablen starten
- [ ] Test 3: Code-Verifikation im Container
- [ ] Test 4: Code-Update testen (Git Pull)
- [ ] Test 5: Application Health Check
### Nach Test:
- [ ] Alle Tests erfolgreich
- [ ] Application läuft korrekt
- [ ] Code ist aktuell
---
## 🚀 Nächste Schritte nach erfolgreichem Test
1. ✅ Git-basiertes Deployment dokumentieren
2. ✅ In CI/CD Pipeline integrieren (optional)
3. ✅ Dokumentation aktualisieren
---
**Bereit zum Testen!** 🧪

45
deployment/docs/tests/quick-test.md Normal file
View File

@@ -0,0 +1,45 @@
# Quick Git Deployment Test
## ✅ Verifikation ohne Container
Alle Dateien sind korrekt konfiguriert:
### 1. Entrypoint Script (`docker/entrypoint.sh`)
- ✅ `GIT_REPOSITORY_URL` Check vorhanden (Zeile 30)
- ✅ Git Clone/Pull Funktionalität implementiert
- ✅ Composer Install integriert
### 2. Docker Compose (`deployment/stacks/application/docker-compose.yml`)
- ✅ `GIT_REPOSITORY_URL` Environment Variable vorhanden (Zeile 17)
- ✅ `GIT_BRANCH`, `GIT_TOKEN`, `GIT_USERNAME`, `GIT_PASSWORD` vorhanden
### 3. Ansible Template (`deployment/ansible/templates/application.env.j2`)
- ✅ Git-Variablen im Template definiert
### 4. Dockerfile (`Dockerfile.production`)
- ✅ Git installiert
- ✅ Composer installiert
- ✅ Entrypoint kopiert
---
## 🧪 Schneller Test (ohne Container-Start)
```bash
# Prüfen ob GIT_REPOSITORY_URL überall vorhanden ist
grep -c "GIT_REPOSITORY_URL" docker/entrypoint.sh
grep -c "GIT_REPOSITORY_URL" deployment/stacks/application/docker-compose.yml
grep -c "GIT_REPOSITORY_URL" deployment/ansible/templates/application.env.j2
```
**Erwartetes Ergebnis:** Alle sollten > 0 zurückgeben
---
## 🚀 Nächste Schritte zum Testen
1. **Image ist bereits gebaut** ✅
2. **Git-Variablen in .env setzen** (auf Production Server)
3. **Container neu starten** und Logs prüfen
Siehe `TEST_GIT_DEPLOYMENT.md` für detaillierte Anleitung.

144
deployment/docs/tests/recommended-test-flow.md Normal file
View File

@@ -0,0 +1,144 @@
# 🎯 Empfohlener Test-Workflow für Git-Deployment
## Meine Empfehlung: **Schritt-für-Schritt mit Checks**
### Warum?
- ✅ Minimiert Risiko von Fehlern
- ✅ Erlaubt Verifikation nach jedem Schritt
- ✅ Einfaches Rollback bei Problemen
- ✅ Klare Fehlerdiagnose
---
## 📋 Workflow
### Schritt 1: Image pushen (falls nötig)
**Wann nötig?**
- Wenn Production-Server das Image aus der Registry zieht
- Wenn Image lokal gebaut wurde und noch nicht gepusht
**Befehl:**
```bash
# Im Projekt-Root
docker push registry.michaelschiemer.de/framework:latest
```
**Check:**
```bash
# Prüfen ob Image in Registry ist (optional)
curl -k https://registry.michaelschiemer.de/v2/framework/tags/list
```
---
### Schritt 2: Git-Variablen setzen (via Ansible)
**Warum Ansible?**
- ✅ Automatisiert und reproduzierbar
- ✅ Aktualisiert .env korrekt
- ✅ Startet Container automatisch neu
**Befehl:**
```bash
cd deployment/ansible
ansible-playbook -i inventory/production.yml \
playbooks/sync-code.yml \
-e "git_repo_url=https://git.michaelschiemer.de/michael/michaelschiemer.git" \
-e "git_branch=main"
```
**Was passiert?**
1. .env Datei wird mit Git-Variablen aktualisiert
2. Container wird neu gestartet
3. Entrypoint führt Git Clone/Pull aus
4. Logs werden angezeigt
---
### Schritt 3: Logs prüfen
**Auf Production Server:**
```bash
ssh deploy@94.16.110.151
# Logs mit Git-Filter
docker logs app --tail 100 | grep -E "(Git|Clone|Pull|✅|❌)"
# Oder vollständige Logs
docker logs app --tail 50
```
**Erwartete Logs:**
```
📥 Cloning/Pulling code from Git repository...
📥 Cloning repository from https://git.michaelschiemer.de/... (branch: main)
📦 Installing/updating Composer dependencies...
✅ Git sync completed
```
---
### Schritt 4: Code-Verifikation
**Prüfen ob Code im Container ist:**
```bash
docker exec app ls -la /var/www/html/ | head -20
docker exec app test -d /var/www/html/.git && echo "✅ Git repo vorhanden" || echo "❌ Fehlt"
docker exec app test -f /var/www/html/composer.json && echo "✅ composer.json vorhanden" || echo "❌ Fehlt"
```
---
### Schritt 5: Application Health Check
```bash
curl -f https://michaelschiemer.de/health || echo "❌ Health Check fehlgeschlagen"
```
---
## 🎯 Mein konkreter Vorschlag
**Starte mit Schritt 2** (Git-Variablen setzen via Ansible), weil:
1. **Ansible prüft automatisch**, ob alles vorhanden ist
2. **Startet Container automatisch** neu
3. **Zeigt Logs direkt** an
4. **Minimaler Aufwand** - ein Befehl
Falls das Image noch nicht in der Registry ist, wird der Container automatisch das neue Image ziehen beim `docker compose up`.
---
## 🚨 Alternative: Lokaler Test (falls gewünscht)
Falls du erst lokal testen möchtest:
```bash
# Lokal Container starten mit Git-Variablen
cd deployment/stacks/application
# .env erstellen/kopieren
cp .env.example .env
# Git-Variablen hinzufügen
echo "" >> .env
echo "GIT_REPOSITORY_URL=https://git.michaelschiemer.de/michael/michaelschiemer.git" >> .env
echo "GIT_BRANCH=main" >> .env
# Container starten
docker compose up -d app
# Logs prüfen
docker compose logs app | grep -E "(Git|Clone|Pull)"
```
---
## ✅ Entscheidung
**Meine Empfehlung:** Starte mit **Schritt 2** (Ansible Playbook). Das ist der sauberste und sicherste Weg.
Soll ich das für dich ausführen?

277
deployment/docs/tests/test-git-deployment.md Normal file
View File

@@ -0,0 +1,277 @@
# Git-basiertes Deployment - Test Anleitung
**Datum:** 2025-01-31
**Status:** ⏳ Ready to Test
---
## ✅ Vorbereitung abgeschlossen
### Implementiert:
- ✅ `docker/entrypoint.sh` - Git Clone/Pull Funktionalität
- ✅ `Dockerfile.production` - Git + Composer installiert
- ✅ `deployment/stacks/application/docker-compose.yml` - Git Environment Variables
- ✅ `deployment/ansible/templates/application.env.j2` - Git Template Variablen
- ✅ `deployment/ansible/playbooks/sync-code.yml` - Code-Sync Playbook
---
## 🧪 Test-Schritte
### Schritt 1: Image neu bauen (mit Git-Funktionalität)
**Ziel:** Sicherstellen dass Image die Git-Funktionalität enthält
```bash
# Im Projekt-Root
docker build -f Dockerfile.production \
-t registry.michaelschiemer.de/framework:test-git \
.
# Image pushen
docker push registry.michaelschiemer.de/framework:test-git
```
**Prüfen:**
```bash
# Git installiert?
docker run --rm registry.michaelschiemer.de/framework:test-git git --version
# Composer installiert?
docker run --rm registry.michaelschiemer.de/framework:test-git composer --version
# Entrypoint hat Git-Logik?
docker run --rm registry.michaelschiemer.de/framework:test-git cat /usr/local/bin/entrypoint.sh | grep -A 5 "GIT_REPOSITORY_URL"
```
---
### Schritt 2: Git-Variablen in .env setzen (auf Production Server)
**Ziel:** Git-Repository-URL in .env konfigurieren
```bash
# Option A: Via Ansible Playbook (Empfohlen)
cd deployment/ansible
ansible-playbook -i inventory/production.yml \
playbooks/sync-code.yml \
-e "git_repo_url=https://git.michaelschiemer.de/michael/michaelschiemer.git" \
-e "git_branch=main"
```
**Oder manuell auf Production-Server:**
```bash
# SSH zum Production-Server
ssh deploy@94.16.110.151
# .env bearbeiten
cd ~/deployment/stacks/application
nano .env
# Folgende Zeilen hinzufügen:
GIT_REPOSITORY_URL=https://git.michaelschiemer.de/michael/michaelschiemer.git
GIT_BRANCH=main
```
**Wenn Repository privat ist (Token hinzufügen):**
```bash
# Token in .env hinzufügen:
GIT_TOKEN=your_git_token_here
```
---
### Schritt 3: Container mit Git-Variablen starten
**Ziel:** Prüfen ob Container Git Clone/Pull beim Start ausführt
```bash
# Auf Production-Server
cd ~/deployment/stacks/application
# Container neu starten
docker compose restart app
# Oder falls Container noch nicht läuft:
docker compose up -d app
# Logs prüfen (sollte Git Clone/Pull zeigen)
docker logs app --tail 100 | grep -E "(Git|Clone|Pull|✅|❌)"
```
**Erwartete Logs:**
```
📥 Cloning/Pulling code from Git repository...
📥 Cloning repository from https://git.michaelschiemer.de/michael/michaelschiemer.git (branch: main)...
📦 Installing/updating Composer dependencies...
✅ Git sync completed
```
---
### Schritt 4: Code-Verifikation im Container
**Ziel:** Prüfen ob Code tatsächlich im Container ist
```bash
# Auf Production-Server
docker exec app ls -la /var/www/html/ | head -20
# Prüfen ob wichtige Dateien vorhanden sind
docker exec app test -f /var/www/html/composer.json && echo "✅ composer.json vorhanden" || echo "❌ Fehlt"
docker exec app test -d /var/www/html/src && echo "✅ src/ vorhanden" || echo "❌ Fehlt"
docker exec app test -d /var/www/html/.git && echo "✅ .git vorhanden" || echo "❌ Fehlt"
# Prüfen welcher Commit
docker exec app sh -c "cd /var/www/html && git log --oneline -1"
```
**Erwartetes Ergebnis:**
- ✅ Dateien sind im Container
- ✅ `.git` Verzeichnis existiert (zeigt dass Git Clone funktioniert hat)
- ✅ Git Commit zeigt aktuellen Stand
---
### Schritt 5: Code-Update testen (Git Pull)
**Ziel:** Prüfen ob `sync-code.yml` Playbook funktioniert
```bash
# Lokal (auf Dev-Machine)
cd deployment/ansible
# Sync-Code Playbook ausführen
ansible-playbook -i inventory/production.yml \
playbooks/sync-code.yml \
-e "git_branch=main"
# Container-Logs prüfen (auf Production-Server)
ssh deploy@94.16.110.151
docker logs app --tail 50 | grep -E "(Git|Pull|✅)"
```
**Erwartetes Ergebnis:**
- ✅ Playbook führt erfolgreich aus
- ✅ Container wird neu gestartet
- ✅ Logs zeigen "🔄 Pulling latest changes from main..."
- ✅ Code wird aktualisiert
---
### Schritt 6: Application Health Check
**Ziel:** Prüfen ob Application nach Git-Sync noch funktioniert
```bash
# Health Check
curl -f https://michaelschiemer.de/health || echo "❌ Health Check fehlgeschlagen"
# Application Test
curl -f https://michaelschiemer.de/ || echo "❌ Application fehlgeschlagen"
```
**Erwartetes Ergebnis:**
- ✅ Health Check erfolgreich
- ✅ Application läuft
---
## 🔧 Troubleshooting
### Problem: Container zeigt keine Git-Logs
**Check 1: Prüfen ob GIT_REPOSITORY_URL gesetzt ist**
```bash
docker exec app env | grep GIT_REPOSITORY_URL
```
**Check 2: Prüfen Entrypoint Script**
```bash
docker exec app cat /usr/local/bin/entrypoint.sh | grep -A 10 "GIT_REPOSITORY_URL"
```
**Check 3: Prüfen ob Git installiert ist**
```bash
docker exec app which git
docker exec app git --version
```
**Lösung:**
- Falls nicht gesetzt: Git-Variablen in .env hinzufügen (siehe Schritt 2)
- Falls Entrypoint fehlt: Image neu bauen (siehe Schritt 1)
- Falls Git fehlt: Image neu bauen mit `git` in Dockerfile
---
### Problem: Git Clone fehlgeschlagen
**Check 1: Repository-Zugriff testen**
```bash
docker exec app git clone --depth 1 https://git.michaelschiemer.de/michael/michaelschiemer.git /tmp/test-clone
```
**Check 2: Logs prüfen**
```bash
docker logs app --tail 100 | grep -i "error\|fail"
```
**Mögliche Ursachen:**
1. Repository nicht erreichbar vom Server
2. Falsche Credentials
3. Branch nicht existiert
4. Network-Probleme
**Lösung:**
- Repository-URL prüfen
- Git-Credentials prüfen (Token/Username+Password)
- Branch-Name prüfen
- Network-Verbindung prüfen
---
### Problem: Composer Install fehlgeschlagen
**Check:**
```bash
docker exec app which composer
docker exec app composer --version
docker exec app sh -c "cd /var/www/html && composer install --no-dev --optimize-autoloader --no-interaction"
```
**Lösung:**
- Falls Composer fehlt: Image neu bauen
- Falls Network-Probleme: Network-Verbindung prüfen
---
## 📋 Test-Checkliste
### Vor Test:
- [ ] Image neu gebaut (mit Git-Funktionalität)
- [ ] Image gepusht zur Registry
- [ ] Git-Repository ist erreichbar vom Production-Server
- [ ] Git-Credentials verfügbar (falls private Repository)
- [ ] .env Datei existiert auf Production-Server
### Während Test:
- [ ] Schritt 1: Image neu bauen ✅
- [ ] Schritt 2: Git-Variablen in .env setzen
- [ ] Schritt 3: Container mit Git-Variablen starten
- [ ] Schritt 4: Code-Verifikation im Container
- [ ] Schritt 5: Code-Update testen (Git Pull)
- [ ] Schritt 6: Application Health Check
### Nach Test:
- [ ] Alle Tests erfolgreich
- [ ] Application läuft korrekt
- [ ] Code ist aktuell aus Git
- [ ] Logs zeigen Git-Operationen
---
## 🚀 Ready to Test!
**Nächster Schritt:** Schritt 1 ausführen (Image neu bauen)
**Vollständiger Test-Plan:** Siehe [GIT_DEPLOYMENT_TEST.md](GIT_DEPLOYMENT_TEST.md)

72
deployment/docs/tests/test-results.md Normal file
View File

@@ -0,0 +1,72 @@
# Git Deployment Test - Ergebnis
**Datum:** 2025-01-31
**Status:** ✅ Ansible Playbook erfolgreich ausgeführt
## ✅ Erfolgreiche Schritte
1. **Ansible Playbook ausgeführt**
- `.env` Datei wurde aktualisiert mit:
- `GIT_REPOSITORY_URL=https://git.michaelschiemer.de/michael/michaelschiemer.git`
- `GIT_BRANCH=main`
2. **Container neu gestartet**
- Container wurde erfolgreich neu gestartet
- Git-Sync sollte beim Start ausgeführt werden
3. **Nächster Schritt: Logs prüfen**
- Git-Logs wurden im Playbook-Output nicht gefunden
- Möglicherweise wurden sie noch nicht generiert oder sind in den Logs vorhanden
---
## 🔍 Verifikation nötig
Bitte prüfe die Container-Logs direkt auf dem Production-Server:
```bash
ssh deploy@94.16.110.151
docker logs app --tail 100 | grep -E "(Git|Clone|Pull|✅|❌)"
```
**Oder vollständige Logs:**
```bash
docker logs app --tail 100
```
**Erwartete Logs:**
```
📥 Cloning/Pulling code from Git repository...
📥 Cloning repository from https://git.michaelschiemer.de/... (branch: main)
📦 Installing/updating Composer dependencies...
✅ Git sync completed
```
---
## 🚨 Falls keine Git-Logs vorhanden sind
**Mögliche Ursachen:**
1. Container verwendet noch altes Image ohne Git-Funktionalität
2. Entrypoint-Script wurde nicht korrekt kopiert
3. Environment-Variablen werden nicht korrekt geladen
**Lösung:**
1. Prüfe ob Image aktualisiert wurde: `docker images registry.michaelschiemer.de/framework:latest`
2. Prüfe Entrypoint: `docker exec app cat /usr/local/bin/entrypoint.sh | grep GIT_REPOSITORY_URL`
3. Prüfe Environment: `docker exec app env | grep GIT_REPOSITORY_URL`
---
## ✅ Nächste Schritte
1. **Logs prüfen** (siehe oben)
2. **Code-Verifikation im Container:**
```bash
docker exec app ls -la /var/www/html/ | head -20
docker exec app test -d /var/www/html/.git && echo "✅ Git repo vorhanden" || echo "❌ Fehlt"
```
3. **Application Health Check:**
```bash
curl -f https://michaelschiemer.de/health
```