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:

Build Stage: Build Docker image
Push Stage: Push to private registry
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
docker compose -f stacks/application/docker-compose.yml logs -f app

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

README.md Unescape Escape

Pragmatic Production Deployment Setup

Architecture Overview

Infrastructure Components