michaelschiemer/deployment/README.md

Pragmatic Production Deployment Setup

Architecture Overview

This deployment setup uses separate Docker Compose stacks for better maintainability and clear separation of concerns.

Docker Compose Structure

The project uses a Base + Override Pattern to prevent configuration drift between environments:

• docker-compose.base.yml - Shared base configuration (services, networks, volumes)
• docker-compose.local.yml - Local development overrides (ports, host mounts, debug flags)
• docker-compose.staging.yml - Staging environment overrides (Traefik labels, staging volumes)
• docker-compose.production.yml - Production environment overrides (security, logging, resources)

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.production.yml up

Benefits:

• ✅ Single source of truth for shared configuration
• ✅ Environment-specific differences clearly visible
• ✅ Reduced configuration drift between environments
• ✅ Easier maintenance and updates

Infrastructure Components

Production Server (94.16.110.151)
├── Stack 1: Traefik (Reverse Proxy & SSL)
├── Stack 2: Gitea (Git Server + MySQL + Redis)
├── Stack 3: Docker Registry (Private Registry)
├── Stack 4: Application (PHP + Nginx + Redis + Queue Workers)
├── Stack 5: PostgreSQL (Database)
└── Stack 6: Monitoring (Portainer + Grafana + Prometheus)

Development Machine
└── Gitea Actions Runner (local, Docker-in-Docker)

Deployment Flow

Developer → git push
         ↓
    Gitea (Production)
         ↓
    Gitea Actions (Dev Machine)
         ↓
    Build Docker Image
         ↓
    Push to Private Registry
         ↓
    SSH/Ansible → Production Server
         ↓
    docker compose pull
         ↓
    docker compose up -d

Directory Structure

deployment/
├── ansible/                   # Ansible config, playbooks, inventory, templates
├── gitea-runner/              # Self-hosted Gitea Actions runner stack
├── stacks/                    # Docker Compose stacks
│   ├── application/          # Main PHP application
│   ├── gitea/                # Git server
│   ├── minio/                # Object storage
│   ├── monitoring/           # Portainer, Grafana, Prometheus
│   ├── postgresql/           # PostgreSQL database
│   ├── registry/             # Private Docker registry
│   ├── staging/              # Optional staging stack
│   └── traefik/              # Reverse proxy with SSL certificates
├── docs/                      # 📚 Dokumentation (siehe docs/README.md)
│   ├── guides/               # Anleitungen & Guides
│   ├── reference/            # Referenz-Dokumentation
│   ├── status/               # Status & Tracking
│   ├── tests/                # Test-Dokumentation
│   └── history/              # Logs & Historie
└── README.md (dieses Dokument)

Getting Started

🚀 Quick Start: Code deployen

Einfachste Methode:

git add .
git commit -m "feat: Add new feature"
git push origin main  # → Automatisches Deployment!

Pipeline-Status: https://git.michaelschiemer.de/michael/michaelschiemer/actions

📖 Vollständige Anleitung: Siehe docs/guides/quick-start.md oder docs/guides/code-change-workflow.md

---

Initial Setup (nur bei erstem Setup)

Prerequisites:

Production Server:

• Docker & Docker Compose installed
• Firewall configured (ports 80, 443, 2222)
• User deploy with Docker permissions
• SSH access configured

Development Machine:

• Docker & Docker Compose installed
• Ansible installed
• SSH key configured for production server

Deployment via Ansible:

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

Dieses Playbook deployed alle Stacks:

• Traefik (Reverse Proxy & SSL)
• PostgreSQL (Database)
• Docker Registry (Private Registry)
• Gitea (Git Server)
• Monitoring (Portainer, Grafana, Prometheus)
• Application Stack (PHP Application + Nginx + Redis + Queue Workers)

📖 Vollständige Setup-Anleitung: Siehe SETUP-GUIDE.md

Stack Documentation

Each stack has its own README with detailed configuration:

• Traefik - Reverse proxy setup
• Gitea - Git server configuration
• Registry - Private registry setup
• Application - Application deployment
• PostgreSQL - Database configuration
• Monitoring - Monitoring stack

Deployment Commands

Code deployen (Image-basiert)

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/deploy-update.yml \
  -e "image_tag=abc1234-1696234567"

Code synchen (Git-basiert)

cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/sync-code.yml \
  -e "git_branch=main"

Rollback zu vorheriger Version

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

📖 Vollständige Command-Referenz: Siehe docs/guides/deployment-commands.md

Update Specific Stack

cd stacks/<stack-name>
docker compose pull
docker compose up -d

CI/CD Pipeline

The CI/CD pipeline is defined in .gitea/workflows/production-deploy.yml and runs automatically on push to main branch.

Quick Start: Deploy Code Changes

# 1. Make changes locally
# ... edit files ...

# 2. Commit changes
git add .
git commit -m "feat: Add new feature"

# 3. Push to main → Automatic deployment starts
git push origin main

What happens automatically:

• ✅ Tests run (~2-5 min)
• ✅ Docker image is built (~3-5 min)
• ✅ Image is pushed to registry (~1-2 min)
• ✅ Ansible deployment runs (~2-4 min)
• ✅ Application stack is updated

Total time: ~8-15 minutes

Status check:

• Pipeline status: https://git.michaelschiemer.de/michael/michaelschiemer/actions
• Application status: ssh deploy@94.16.110.151 "cd ~/deployment/stacks/application && docker compose ps"

📖 Vollständige Dokumentation:

• docs/guides/quick-start.md ⭐ - Schnellstart-Guide für Deployment
• docs/guides/code-change-workflow.md - Kompletter Guide für Codeänderungen
• docs/reference/application-stack.md - Detaillierter Deployment-Ablauf
• docs/status/ci-cd-status.md - CI/CD Pipeline Status & Checkliste
• docs/status/deployment-summary.md - Projekt-Status Übersicht

Pipeline Details

The CI/CD pipeline runs on push to main branch:

1. Build Stage: Build Docker image
2. Push Stage: Push to private registry
3. Deploy Stage: Deploy to production via Ansible

Monitoring

Access monitoring tools:

• Portainer: https://portainer.yourdomain.com
• Grafana: https://grafana.yourdomain.com
• Prometheus: https://prometheus.yourdomain.com

Backup & Recovery

Current State

Infrastructure backups are handled per stack. The PostgreSQL stack ships helper scripts under stacks/postgresql/scripts/ (see backup.sh and restore.sh). Registry and Gitea data snapshots are currently managed manually on the host.

Roadmap

An Ansible-level backup/restore playbook is still planned. Track progress in DEPLOYMENT-TODO.md and update this section once the playbook is available.

Security

• All external services behind Traefik with HTTPS
• Private registry with BasicAuth
• Secrets managed via Ansible Vault
• Regular security updates via Watchtower

Troubleshooting

Check Stack Health

cd stacks/<stack-name>
docker compose ps
docker compose logs -f

Check Service Connectivity

curl -I https://app.yourdomain.com
docker network inspect traefik-public

View Logs

# Application logs (Production)
docker compose -f docker-compose.base.yml -f docker-compose.production.yml logs -f php

# Traefik logs
docker compose -f stacks/traefik/docker-compose.yml logs -f

📚 Dokumentation Index

Vollständige Dokumentations-Übersicht: Siehe docs/README.md

Wichtigste Dokumente:

• docs/guides/quick-start.md ⭐ - Schnellstart
• docs/guides/code-change-workflow.md - Code deployen
• docs/reference/application-stack.md - Deployment-Details
• docs/status/ci-cd-status.md - CI/CD Status
• docs/status/deployment-summary.md - Projekt-Übersicht

Support

Für spezifische Fragen helfen die folgenden Dokumente weiter:

• docs/reference/workflow-troubleshooting.md – Fehleranalyse für Laufzeiten & Pipelines
• docs/status/ci-cd-status.md – Pipeline-Status & Checklisten
• docs/status/deployment-summary.md – Aktueller Projektüberblick
• docs/reference/application-stack.md – Detaillierte Deployment-Schritte

License

This deployment configuration is part of the Custom PHP Framework project.