michaelschiemer/deployment/README.md

Two-Layer Deployment System

Architecture Overview

Das Deployment-System verwendet eine klare Trennung zwischen Infrastruktur-Layer und Application-Layer:

• Layer 1 (Infrastruktur): Traefik, Gitea, PostgreSQL - separat deployt, läuft dauerhaft
• Layer 2 (Application): PHP-App mit Nginx, Redis, Queue Workers - deployt aus dem Projekt

Vorteile

• ✅ Klare Trennung: Infrastruktur vs. Application
• ✅ Einfach zu verwalten: Jede Schicht separat verwaltbar
• ✅ Gitea separat: Unabhängige Updates möglich
• ✅ Nutzt bestehende Struktur: Base+Override Pattern bleibt erhalten
• ✅ Skalierbar: Einfach erweiterbar

Infrastructure Layer

Die Infrastruktur-Stacks befinden sich in deployment/infrastructure/:

• Traefik - Reverse Proxy mit SSL-Zertifikaten
• Gitea - Git Server mit eigener PostgreSQL-Instanz
• PostgreSQL - Shared Database für Application-Stacks

Dokumentation: Siehe deployment/infrastructure/README.md

Deployment:

cd deployment/infrastructure
./deploy.sh all  # Deploys alle Stacks in korrekter Reihenfolge

Application Layer

Die Application wird aus dem Projekt deployt und nutzt externe Infrastruktur über Docker Networks.

Docker Compose Structure

Das Projekt verwendet ein Base + Override Pattern:

• docker-compose.base.yml - Gemeinsame Basis-Konfiguration
• docker-compose.local.yml - Local Development Overrides
• docker-compose.staging.yml - Staging Environment Overrides
• docker-compose.prod.yml - Production Environment Overrides

Usage:

# Local development
docker compose -f docker-compose.base.yml -f docker-compose.local.yml up

# Staging
docker compose -f docker-compose.base.yml -f docker-compose.staging.yml up

# Production
docker compose -f docker-compose.base.yml -f docker-compose.prod.yml up

Deployment Workflow

Automatisches Deployment (Gitea Actions)

Workflow: .gitea/workflows/deploy.yml

• Trigger: Push zu staging oder main Branch
• Führt automatisch Deployment-Script aus
• Status-Reporting zurück zu Gitea

Manuelles Deployment (SSH-Script)

Script: deployment/scripts/deploy.sh

# Staging deployen
./deployment/scripts/deploy.sh staging

# Production deployen
./deployment/scripts/deploy.sh production

# Mit Image-Build
./deployment/scripts/deploy.sh staging build

Was passiert:

1. Secrets-Prüfung
2. Infrastructure-Networks-Prüfung
3. Docker Images pullen (optional: builden)
4. Docker Compose Up
5. Health Checks
6. Status-Report

Networks

Das System verwendet folgende Docker Networks:

• traefik-public - Wird von Traefik erstellt, für externe Zugriffe
• infrastructure - Für interne Infrastruktur-Kommunikation (Gitea ↔ PostgreSQL)
• app-internal - Wird von PostgreSQL erstellt, für Application ↔ PostgreSQL Kommunikation
• app-backend - Internes Network für Application-Services (PHP ↔ Nginx ↔ Redis)

Secrets Management

Secrets werden in deployment/secrets/ Verzeichnissen gespeichert:

deployment/
├── infrastructure/
│   ├── traefik/secrets/
│   ├── gitea/secrets/
│   └── postgresql/secrets/
└── secrets/
    ├── staging/
    │   ├── db_password.txt
    │   ├── redis_password.txt
    │   └── app_key.txt
    └── production/
        ├── db_password.txt
        ├── redis_password.txt
        └── app_key.txt

Wichtig: Secrets-Dateien sind gitignored und müssen manuell erstellt werden.

Siehe deployment/infrastructure/SECRETS.md für Details.

Quick Start

Initial Setup (einmalig)

1. Infrastruktur deployen:

   cd deployment/infrastructure
   ./deploy.sh all
   

2. Secrets konfigurieren:

   # Siehe deployment/infrastructure/SECRETS.md
   

3. Application deployen:

   ./deployment/scripts/deploy.sh staging
   

Normaler Deployment-Workflow

1. Code ändern und committen:

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

2. Testen auf Staging:

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

3. Nach erfolgreichem Test zu Production:

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

Migration vom alten System

Falls Sie vom alten System migrieren, siehe MIGRATION.md für eine detaillierte Anleitung.

Directory Structure

deployment/
├── infrastructure/          # Infrastructure Layer
│   ├── traefik/
│   ├── gitea/
│   ├── postgresql/
│   ├── deploy.sh
│   └── README.md
├── scripts/                # Deployment Scripts
│   └── deploy.sh
├── secrets/                # Application Secrets (gitignored)
│   ├── staging/
│   └── production/
├── legacy/                 # Altes System (nur Referenz)
└── README.md (dieses Dokument)

Troubleshooting

Infrastructure-Probleme

# Traefik nicht erreichbar
cd deployment/infrastructure/traefik
docker compose logs -f

# PostgreSQL-Verbindungsprobleme
cd deployment/infrastructure/postgresql
docker compose logs postgres
docker network inspect app-internal

Application-Probleme

# Container-Status prüfen
docker compose -f docker-compose.base.yml -f docker-compose.prod.yml ps

# Logs anzeigen
docker compose -f docker-compose.base.yml -f docker-compose.prod.yml logs -f

# Health Checks
curl https://michaelschiemer.de/health

Network-Probleme

# Networks prüfen
docker network ls
docker network inspect traefik-public
docker network inspect app-internal
docker network inspect infrastructure

Weitere Dokumentation

• Infrastructure Layer - Infrastruktur-Dokumentation
• Migration Guide - Migration vom alten System
• Secrets Management - Secrets-Verwaltung

Support

Bei Problemen:

1. Logs sammeln: docker compose logs > debug_logs.txt
2. Container-Status: docker compose ps
3. Network-Status: docker network ls