michaelschiemer/deployment/ansible/playbooks/README.md

Ansible Playbooks - Übersicht

Neue Struktur

Die Playbooks wurden reorganisiert in eine klare Verzeichnisstruktur:

playbooks/
├── setup/              # Initial Setup
│   ├── infrastructure.yml
│   ├── gitea.yml
│   └── ssl.yml
├── deploy/             # Deployment
│   ├── complete.yml
│   ├── image.yml
│   └── code.yml
├── manage/             # Management (konsolidiert)
│   ├── traefik.yml
│   ├── gitea.yml
│   └── application.yml
├── diagnose/           # Diagnose (konsolidiert)
│   ├── gitea.yml
│   ├── traefik.yml
│   └── application.yml
└── maintenance/        # Wartung
    ├── backup.yml
    ├── backup-before-redeploy.yml
    ├── cleanup.yml
    ├── rollback-redeploy.yml
    └── system.yml

Verfügbare Playbooks

Hinweis: Die meisten Playbooks wurden in wiederverwendbare Roles refactored. Die Playbooks sind jetzt Wrapper, die die entsprechenden Role-Tasks aufrufen. Dies verbessert Wiederverwendbarkeit, Wartbarkeit und folgt Ansible Best Practices.

Setup (Initial Setup)

• setup/infrastructure.yml - Deployed alle Stacks (Traefik, PostgreSQL, Redis, Registry, Gitea, Monitoring, Production)
• setup/gitea.yml - Setup Gitea Initial Configuration (Wrapper für gitea Role, tasks_from: setup)
• setup/ssl.yml - SSL Certificate Setup (Wrapper für traefik Role, tasks_from: ssl)
• setup/redeploy-traefik-gitea-clean.yml - Clean redeployment of Traefik and Gitea stacks
• setup/REDEPLOY_GUIDE.md - Step-by-step guide for redeployment

Deployment

• deploy/complete.yml - Complete deployment (code + image + dependencies)
• deploy/image.yml - Docker Image Deployment (wird von CI/CD Workflows verwendet)
• deploy/code.yml - Deploy Application Code via Git (Wrapper für application Role, tasks_from: deploy_code)

Management (Konsolidiert)

Traefik Management

• manage/traefik.yml - Consolidated Traefik management
  • --tags stabilize: Fix acme.json, ensure running, monitor stability
  • --tags disable-auto-restart: Check and document auto-restart mechanisms
• restart-traefik.yml - Restart Traefik Container (Wrapper für traefik Role, tasks_from: restart)
• recreate-traefik.yml - Recreate Traefik Container (Wrapper für traefik Role, tasks_from: restart mit traefik_restart_action: recreate)
• deploy-traefik-config.yml - Deploy Traefik Configuration Files (Wrapper für traefik Role, tasks_from: config)
• check-traefik-acme-logs.yml - Check Traefik ACME Challenge Logs (Wrapper für traefik Role, tasks_from: logs)

Gitea Management

• manage/gitea.yml - Consolidated Gitea management
  • --tags restart: Restart Gitea container
  • --tags fix-timeouts: Restart Gitea and Traefik to fix timeouts
  • --tags fix-ssl: Fix SSL/routing issues
  • --tags fix-servers-transport: Update ServersTransport configuration
  • --tags complete: Complete fix (stop runner, restart services, verify)
• check-and-restart-gitea.yml - Check and Restart Gitea if Unhealthy (Wrapper für gitea Role, tasks_from: restart)
• fix-gitea-runner-config.yml - Fix Gitea Runner Configuration (Wrapper für gitea Role, tasks_from: runner mit gitea_runner_action: fix)
• register-gitea-runner.yml - Register Gitea Runner (Wrapper für gitea Role, tasks_from: runner mit gitea_runner_action: register)
• update-gitea-config.yml - Update Gitea Configuration (Wrapper für gitea Role, tasks_from: config)
• setup-gitea-repository.yml - Setup Gitea Repository (Wrapper für gitea Role, tasks_from: repository)

Application Management

• manage/application.yml - Consolidated application management (to be created)
• sync-application-code.yml - Synchronize Application Code via Rsync (Wrapper für application Role, tasks_from: deploy_code mit application_deployment_method: rsync)
• install-composer-dependencies.yml - Install Composer Dependencies (Wrapper für application Role, tasks_from: composer)
• check-container-status.yml - Check Container Status (Wrapper für application Role, tasks_from: health_check)
• check-container-logs.yml - Check Container Logs (Wrapper für application Role, tasks_from: logs)
• check-worker-logs.yml - Check Worker and Scheduler Logs (Wrapper für application Role, tasks_from: logs mit application_logs_check_vendor: true)
• check-final-status.yml - Check Final Container Status (Wrapper für application Role, tasks_from: health_check mit application_health_check_final: true)
• fix-container-issues.yml - Fix Container Issues (Wrapper für application Role, tasks_from: containers mit application_container_action: fix)
• fix-web-container.yml - Fix Web Container Permissions (Wrapper für application Role, tasks_from: containers mit application_container_action: fix-web)
• recreate-containers-with-env.yml - Recreate Containers with Environment Variables (Wrapper für application Role, tasks_from: containers mit application_container_action: recreate-with-env)
• sync-and-recreate-containers.yml - Sync and Recreate Containers (Wrapper für application Role, tasks_from: containers mit application_container_action: sync-recreate)

Diagnose (Konsolidiert)

Gitea Diagnose

• diagnose/gitea.yml - Consolidated Gitea diagnosis
  • Basic checks (always): Container status, health endpoints, network connectivity, service discovery
  • --tags deep: Resource usage, multiple connection tests, log analysis
  • --tags complete: All checks including app.ini, ServersTransport, etc.

Traefik Diagnose

• diagnose/traefik.yml - Consolidated Traefik diagnosis
  • Basic checks (always): Container status, restart count, recent logs
  • --tags restart-source: Find source of restart loops (cronjobs, systemd, scripts)
  • --tags monitor: Monitor for restarts over time

Maintenance

• maintenance/backup.yml - Erstellt Backups von PostgreSQL, Application Data, Gitea, Registry
• maintenance/backup-before-redeploy.yml - Backup before redeploy (Gitea data, SSL certificates, configurations)
• maintenance/rollback-redeploy.yml - Rollback from redeploy backup
• maintenance/cleanup.yml - Stoppt und entfernt alle Container, bereinigt Netzwerke und Volumes (für vollständigen Server-Reset)
• maintenance/system.yml - System-Updates, Unattended-Upgrades, Docker-Pruning
• rollback.yml - Rollback zu vorheriger Version

WireGuard

• generate-wireguard-client.yml - Generiert WireGuard Client-Config
• wireguard-routing.yml - Konfiguriert WireGuard Routing
• setup-wireguard-host.yml - WireGuard VPN Setup

Initial Deployment

• build-initial-image.yml - Build und Push des initialen Docker Images (für erstes Deployment)

CI/CD & Development

• setup-gitea-runner-ci.yml - Gitea Runner CI Setup
• install-docker.yml - Docker Installation auf Server

Entfernte/Konsolidierte Playbooks

Die folgenden Playbooks wurden konsolidiert oder entfernt:

Konsolidiert in diagnose/gitea.yml:

• diagnose-gitea-timeouts.yml
• diagnose-gitea-timeout-deep.yml
• diagnose-gitea-timeout-live.yml
• diagnose-gitea-timeouts-complete.yml
• comprehensive-gitea-diagnosis.yml

Konsolidiert in manage/gitea.yml:

• fix-gitea-timeouts.yml
• fix-gitea-traefik-connection.yml
• fix-gitea-ssl-routing.yml
• fix-gitea-servers-transport.yml
• fix-gitea-complete.yml
• restart-gitea-complete.yml
• restart-gitea-with-cache.yml

Konsolidiert in diagnose/traefik.yml:

• diagnose-traefik-restarts.yml
• find-traefik-restart-source.yml
• monitor-traefik-restarts.yml
• monitor-traefik-continuously.yml
• verify-traefik-fix.yml

Konsolidiert in manage/traefik.yml:

• stabilize-traefik.yml
• disable-traefik-auto-restarts.yml

Entfernt (veraltet/redundant):

• update-gitea-traefik-service.yml - Deprecated (wie in Code dokumentiert)
• ensure-gitea-traefik-discovery.yml - Redundant
• test-gitea-after-fix.yml - Temporär
• find-ansible-automation-source.yml - Temporär

Verschoben:

• setup-infrastructure.yml → setup/infrastructure.yml
• deploy-complete.yml → deploy/complete.yml
• deploy-image.yml → deploy/image.yml
• deploy-application-code.yml → deploy/code.yml
• setup-ssl-certificates.yml → setup/ssl.yml
• setup-gitea-initial-config.yml → setup/gitea.yml
• cleanup-all-containers.yml → maintenance/cleanup.yml

Verwendung

Standard-Verwendung

cd deployment/ansible
ansible-playbook -i inventory/production.yml playbooks/<playbook>.yml --vault-password-file secrets/.vault_pass

Konsolidierte Playbooks mit Tags

Gitea Diagnose:

# Basic diagnosis (default)
ansible-playbook -i inventory/production.yml playbooks/diagnose/gitea.yml --vault-password-file secrets/.vault_pass

# Deep diagnosis
ansible-playbook -i inventory/production.yml playbooks/diagnose/gitea.yml --tags deep --vault-password-file secrets/.vault_pass

# Complete diagnosis
ansible-playbook -i inventory/production.yml playbooks/diagnose/gitea.yml --tags complete --vault-password-file secrets/.vault_pass

Gitea Management:

# Restart Gitea
ansible-playbook -i inventory/production.yml playbooks/manage/gitea.yml --tags restart --vault-password-file secrets/.vault_pass

# Fix timeouts
ansible-playbook -i inventory/production.yml playbooks/manage/gitea.yml --tags fix-timeouts --vault-password-file secrets/.vault_pass

# Complete fix
ansible-playbook -i inventory/production.yml playbooks/manage/gitea.yml --tags complete --vault-password-file secrets/.vault_pass

Traefik Diagnose:

# Basic diagnosis
ansible-playbook -i inventory/production.yml playbooks/diagnose/traefik.yml --vault-password-file secrets/.vault_pass

# Find restart source
ansible-playbook -i inventory/production.yml playbooks/diagnose/traefik.yml --tags restart-source --vault-password-file secrets/.vault_pass

# Monitor restarts
ansible-playbook -i inventory/production.yml playbooks/diagnose/traefik.yml --tags monitor --vault-password-file secrets/.vault_pass

Traefik Management:

# Stabilize Traefik
ansible-playbook -i inventory/production.yml playbooks/manage/traefik.yml --tags stabilize --vault-password-file secrets/.vault_pass

Redeploy:

# With automatic backup
ansible-playbook -i inventory/production.yml playbooks/setup/redeploy-traefik-gitea-clean.yml --vault-password-file secrets/.vault_pass

# With existing backup
ansible-playbook -i inventory/production.yml playbooks/setup/redeploy-traefik-gitea-clean.yml \
  --vault-password-file secrets/.vault_pass \
  -e "backup_name=redeploy-backup-1234567890" \
  -e "skip_backup=true"

Rollback:

ansible-playbook -i inventory/production.yml playbooks/maintenance/rollback-redeploy.yml \
  --vault-password-file secrets/.vault_pass \
  -e "backup_name=redeploy-backup-1234567890"

Role-basierte Playbooks

Die meisten Playbooks sind jetzt Wrapper, die Roles verwenden. Die Funktionalität bleibt gleich, aber die Implementierung ist jetzt in wiederverwendbaren Roles organisiert:

Beispiel: Traefik Restart

# Alte Methode (funktioniert noch, ruft jetzt aber die Role auf):
ansible-playbook -i inventory/production.yml playbooks/restart-traefik.yml --vault-password-file secrets/.vault_pass

# Direkte Role-Verwendung (alternative Methode):
ansible-playbook -i inventory/production.yml -e "traefik_restart_action=restart" -e "traefik_show_status=true" playbooks/restart-traefik.yml

Beispiel: Gitea Runner Fix

ansible-playbook -i inventory/production.yml playbooks/fix-gitea-runner-config.yml --vault-password-file secrets/.vault_pass

Beispiel: Application Code Deployment

# Git-basiert (Standard):
ansible-playbook -i inventory/production.yml playbooks/deploy/code.yml \
  -e "deployment_environment=staging" \
  -e "git_branch=staging" \
  --vault-password-file secrets/.vault_pass

# Rsync-basiert (für Initial Deployment):
ansible-playbook -i inventory/production.yml playbooks/sync-application-code.yml \
  --vault-password-file secrets/.vault_pass

Role-Struktur

Die Playbooks verwenden jetzt folgende Roles:

traefik Role

• Tasks: restart, config, logs, ssl
• Location: roles/traefik/tasks/
• Defaults: roles/traefik/defaults/main.yml

gitea Role

• Tasks: restart, runner, config, setup, repository
• Location: roles/gitea/tasks/
• Defaults: roles/gitea/defaults/main.yml

application Role

• Tasks: deploy_code, composer, containers, health_check, logs, deploy
• Location: roles/application/tasks/
• Defaults: roles/application/defaults/main.yml

Vorteile der neuen Struktur

1. Klarheit: Klare Verzeichnisstruktur nach Funktion
2. Konsolidierung: Redundante Playbooks zusammengeführt
3. Tags: Selektive Ausführung mit Tags
4. Wiederverwendbarkeit: Tasks können in mehreren Playbooks genutzt werden
5. Wartbarkeit: Änderungen zentral in Roles
6. Best Practices: Folgt Ansible-Empfehlungen