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](infrastructure/README.md)

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

```bash
# 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](infrastructure/SECRETS.md) für Details.

## Quick Start

### Initial Setup (einmalig)

1. **Infrastruktur deployen:**
   ```bash
   cd deployment/infrastructure
   ./deploy.sh all
   ```

2. **Secrets konfigurieren:**
   ```bash
   # Siehe deployment/infrastructure/SECRETS.md
   ```

3. **Application deployen:**
   ```bash
   ./deployment/scripts/deploy.sh staging
   ```

### Normaler Deployment-Workflow

1. **Code ändern und committen:**
   ```bash
   git add .
   git commit -m "feat: Add new feature"
   git push origin staging  # → Automatisches Deployment zu Staging
   ```

2. **Testen auf Staging:**
   - Staging URL: `https://staging.michaelschiemer.de`
   - Tests durchführen

3. **Nach erfolgreichem Test zu Production:**
   ```bash
   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](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

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

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

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

## Weitere Dokumentation

- [Infrastructure Layer](infrastructure/README.md) - Infrastruktur-Dokumentation
- [Migration Guide](MIGRATION.md) - Migration vom alten System
- [Secrets Management](infrastructure/SECRETS.md) - 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`