michaelschiemer/deployment/infrastructure/playbooks/README-git-deployment.md

Git-Based Deployment mit Gitea

Übersicht

Das Git-basierte Deployment Playbook (deploy-git-based.yml) ermöglicht Zero-Downtime Deployments mit Gitea als Git-Repository-Server.

Voraussetzungen

1. Gitea Server Setup

Der Gitea Server muss für den Production-Server erreichbar sein. Es gibt zwei Optionen:

Option A: Öffentlich erreichbarer Gitea Server (Empfohlen für Production)

# Gitea muss über das Internet erreichbar sein
git_repo: "git@git.michaelschiemer.de:michael/michaelschiemer.git"

Erforderlich:

• Öffentliche IP oder Domain für Gitea
• Firewall-Regel für Port 2222 (SSH)
• SSL/TLS für Webinterface (Port 9443/3000)

Option B: Gitea auf dem Production-Server

# Gitea läuft auf demselben Server wie die Anwendung
git_repo: "git@localhost:michael/michaelschiemer.git"

Erforderlich:

• Gitea Container auf Production-Server deployen
• Docker Compose Setup auf Production-Server
• Lokale SSH-Konfiguration

2. SSH Key Setup

Der Deploy-User auf dem Production-Server benötigt einen SSH-Key:

# Auf dem Production-Server
ssh-keygen -t ed25519 -C "deployment@michaelschiemer" -f ~/.ssh/gitea_deploy_key -N ""

# Public Key zu Gitea hinzufügen (via Web-UI oder API)
cat ~/.ssh/gitea_deploy_key.pub

3. SSH Keys im Secrets-Verzeichnis

Die SSH Keys müssen im deployment/infrastructure/secrets/ Verzeichnis liegen:

deployment/infrastructure/secrets/
├── .gitignore          # Schützt Keys vor versehentlichem Commit
├── gitea_deploy_key    # Private Key
└── gitea_deploy_key.pub  # Public Key

WICHTIG: Das secrets/ Verzeichnis ist via .gitignore geschützt und darf NIEMALS committed werden!

Deployment-Ablauf

1. SSH Key auf Production-Server kopieren

Das Playbook kopiert automatisch die SSH Keys aus secrets/ auf den Production-Server:

- name: Copy Gitea deploy SSH private key
  copy:
    src: "{{ playbook_dir }}/../secrets/gitea_deploy_key"
    dest: "/home/{{ app_user }}/.ssh/gitea_deploy_key"
    mode: '0600'

2. SSH-Konfiguration

Das Playbook erstellt automatisch die SSH-Konfiguration:

Host localhost
    HostName localhost
    Port 2222
    User git
    IdentityFile ~/.ssh/gitea_deploy_key
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null

Host git.michaelschiemer.de
    HostName git.michaelschiemer.de
    Port 2222
    User git
    IdentityFile ~/.ssh/gitea_deploy_key
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null

3. Git Clone

Das Playbook clont das Repository in ein Release-Verzeichnis:

/var/www/michaelschiemer/
├── releases/
│   ├── 1761524417/     # Timestamp-basierte Releases
│   └── v1.0.0/         # Tag-basierte Releases
├── shared/             # Shared Directories (symlinked)
│   ├── storage/
│   └── .env.production
└── current -> releases/1761524417  # Symlink auf aktives Release

4. Zero-Downtime Deployment

• Neues Release wird geclont
• Dependencies installiert
• Symlinks erstellt
• current Symlink atomar gewechselt
• Health Check durchgeführt
• Bei Fehler: Automatischer Rollback

Deployment ausführen

Standard Deployment (main Branch)

cd deployment/infrastructure
ansible-playbook -i inventories/production/hosts.yml playbooks/deploy-git-based.yml

Tag-basiertes Deployment

ansible-playbook -i inventories/production/hosts.yml playbooks/deploy-git-based.yml \
  --extra-vars "release_tag=v1.0.0"

Custom Branch Deployment

ansible-playbook -i inventories/production/hosts.yml playbooks/deploy-git-based.yml \
  --extra-vars "git_branch=develop"

Konfiguration anpassen

Git Repository URL ändern

In deploy-git-based.yml:

vars:
  git_repo: "git@git.michaelschiemer.de:michael/michaelschiemer.git"
  # Oder für lokales Testing:
  # git_repo: "git@localhost:michael/michaelschiemer.git"

Shared Directories anpassen

vars:
  shared_dirs:
    - storage/logs
    - storage/cache
    - storage/sessions
    - storage/uploads
    - public/uploads

  shared_files:
    - .env.production

Troubleshooting

Fehler: "Connection refused" zu Gitea

Problem: Der Production-Server kann Gitea nicht erreichen.

Lösung:

1. Prüfe, ob Gitea öffentlich erreichbar ist: nc -zv git.michaelschiemer.de 2222
2. Prüfe Firewall-Regeln auf dem Gitea-Server
3. Für lokales Testing: Verwende rsync-based Deployment stattdessen

Fehler: "Permission denied (publickey)"

Problem: SSH Key ist nicht korrekt konfiguriert.

Lösung:

1. Prüfe, ob der Public Key in Gitea hinzugefügt wurde
2. Prüfe SSH Key Permissions: chmod 600 ~/.ssh/gitea_deploy_key
3. Teste SSH-Verbindung manuell: ssh -p 2222 -i ~/.ssh/gitea_deploy_key git@git.michaelschiemer.de

Health Check schlägt fehl

Problem: Deployment-Health-Check failed.

Lösung:

1. Automatischer Rollback wurde durchgeführt
2. Prüfe Logs: tail -f /var/www/michaelschiemer/deploy.log
3. Prüfe Application Logs: /var/www/michaelschiemer/shared/storage/logs/

Comparison: Git-based vs rsync-based

Git-based Deployment (Dieser Playbook)

Vorteile:

• Zero-Downtime durch Symlink-Switch
• Atomare Releases mit Rollback-Fähigkeit
• Git-Historie auf Production-Server
• Einfache Rollbacks zu vorherigen Releases

Nachteile:

• Gitea Server muss erreichbar sein
• Zusätzliche Infrastruktur (Gitea)
• SSH Key Management erforderlich

rsync-based Deployment

Vorteile:

• Keine zusätzliche Infrastruktur
• Funktioniert mit lokalem Development-Environment
• Schneller für kleine Änderungen

Nachteile:

• Kein Zero-Downtime ohne zusätzliche Logik
• Keine Git-Historie auf Server
• Rollback komplizierter

Empfehlung

Für Production: Git-based Deployment mit öffentlich erreichbarem Gitea Server Für Development/Testing: rsync-based Deployment (bereits implementiert und getestet)

Related Files

• deploy-git-based.yml - Git-based Deployment Playbook
• deploy-rsync-based.yml - rsync-based Deployment Playbook (Alternative)
• rollback-git-based.yml - Rollback Playbook für Git-Deployments
• secrets/.gitignore - Schutz für SSH Keys