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.

### 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/
├── stacks/                    # Docker Compose stacks
│   ├── traefik/              # Reverse proxy with SSL
│   ├── gitea/                # Git server
│   ├── registry/             # Private Docker registry
│   ├── application/          # Main PHP application
│   ├── postgres/             # Database
│   └── monitoring/           # Portainer + Grafana + Prometheus
├── ansible/                   # Automation playbooks
│   ├── playbooks/            # Deployment automation
│   ├── inventory/            # Server inventory
│   └── secrets/              # Ansible Vault secrets
└── docs/                      # Deployment documentation
```

## Getting Started

### 🚀 Quick Start: Code deployen

**Einfachste Methode:**
```bash
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 [QUICK_START.md](QUICK_START.md) oder [CODE_CHANGE_WORKFLOW.md](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:**
```bash
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](SETUP-GUIDE.md)

## Stack Documentation

Each stack has its own README with detailed configuration:

- [Traefik](stacks/traefik/README.md) - Reverse proxy setup
- [Gitea](stacks/gitea/README.md) - Git server configuration
- [Registry](stacks/registry/README.md) - Private registry setup
- [Application](stacks/application/README.md) - Application deployment
- [PostgreSQL](stacks/postgres/README.md) - Database configuration
- [Monitoring](stacks/monitoring/README.md) - Monitoring stack

## Deployment Commands

### Code deployen (Image-basiert)
```bash
cd deployment/ansible
ansible-playbook -i inventory/production.yml \
  playbooks/deploy-update.yml \
  -e "image_tag=abc1234-1696234567"
```

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

**📖 Vollständige Command-Referenz:** Siehe [DEPLOYMENT_COMMANDS.md](DEPLOYMENT_COMMANDS.md)

### Update Specific Stack
```bash
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

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

- **[QUICK_START.md](QUICK_START.md)** ⭐ - Schnellstart-Guide für Deployment
- **[CODE_CHANGE_WORKFLOW.md](CODE_CHANGE_WORKFLOW.md)** - Kompletter Guide für Codeänderungen
- **[APPLICATION_STACK_DEPLOYMENT.md](APPLICATION_STACK_DEPLOYMENT.md)** - Detaillierter Deployment-Ablauf
- **[CI_CD_STATUS.md](CI_CD_STATUS.md)** - CI/CD Pipeline Status & Checkliste
- **[DEPLOYMENT_SUMMARY.md](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

### Automated Backups

- **PostgreSQL**: Daily backups with 7-day retention
- **Gitea Data**: Weekly backups
- **Registry Images**: On-demand backups

### Manual Backup
```bash
ansible-playbook -i inventory/production.yml playbooks/backup.yml
```

### Restore from Backup
```bash
ansible-playbook -i inventory/production.yml playbooks/restore.yml
```

## 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
```bash
cd stacks/<stack-name>
docker compose ps
docker compose logs -f
```

### Check Service Connectivity
```bash
curl -I https://app.yourdomain.com
docker network inspect traefik-public
```

### View Logs
```bash
# Application logs
docker compose -f stacks/application/docker-compose.yml logs -f app-php

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

## 📚 Dokumentation Index

**Vollständige Dokumentations-Übersicht:** Siehe [DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md)

**Wichtigste Dokumente:**
- **[QUICK_START.md](QUICK_START.md)** ⭐ - Schnellstart
- **[CODE_CHANGE_WORKFLOW.md](CODE_CHANGE_WORKFLOW.md)** - Code deployen
- **[APPLICATION_STACK_DEPLOYMENT.md](APPLICATION_STACK_DEPLOYMENT.md)** - Deployment-Details
- **[CI_CD_STATUS.md](CI_CD_STATUS.md)** - CI/CD Status
- **[DEPLOYMENT_SUMMARY.md](DEPLOYMENT_SUMMARY.md)** - Projekt-Übersicht

## Support

For issues and questions, see:
- [Troubleshooting Guide](docs/troubleshooting.md)
- [Workflow Troubleshooting](WORKFLOW-TROUBLESHOOTING.md)
- [CI/CD Status](CI_CD_STATUS.md) - Mit Troubleshooting-Section

## Migration from Docker Swarm

See [Migration Guide](docs/migration-from-swarm.md) for detailed instructions on migrating from the old Docker Swarm setup.

## License

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