Einleitung

In diesem Artikel dokumentieren wir die erfolgreiche Deployment und Integration von Gitea in die matzka.cloud Infrastruktur. Gitea ist ein leichtgewichtiger, selbstgehosteter Git-Service, der als vollständige Alternative zu GitHub funktioniert - perfekt für Organisationen, die volle Kontrolle über ihre Repositories benötigen.

Nach intensiver Arbeit an der Infrastruktur haben wir Gitea mit vollständiger HTTPS-Unterstützung, Authentik SSO Integration und automatischen Backups erfolgreich bereitgestellt.

🎯 Übersicht der Deployment

Komponente	Wert	Status
Service	Gitea 1.22 (rootless)	✅ Operational
Domain	git.matzka.cloud	✅ HTTPS (Let's Encrypt)
Database	PostgreSQL 17	✅ Secure (internal)
SSH Port	2222	✅ Forwarded
Email	Mailcow SMTP:587	✅ Configured
SSO	Authentik OIDC	✅ Working
Backups	Daily 03:00 UTC	✅ 30-day retention

Architektur & Komponenten

Deployment Struktur

/opt/docker/gitea/
├── docker-compose.yml          # Gitea + PostgreSQL Stack
├── .env                        # Sicherheitsschlüssel und Passwörter
└── volumes/
    ├── postgres_gitea_data/    # PostgreSQL Datenbank
    ├── gitea_data/             # Repository-Daten
    └── gitea_config/           # Konfigurationsdateien

Netzwerk-Topologie

Gitea ist in ein sorgfältig isoliertes Netzwerk-Setup integriert:

• frontend: Öffentlich zugänglich via Traefik (HTTPS)
• gitea-backend: Internal-only Netzwerk für PostgreSQL
• mailcow-network: Verbindung zu Mailcow für SMTP-Notifications

Container Spezifikationen

Gitea Container (rootless)

• Image: gitea/gitea:1.22-rootless
• User: UID 1000 (non-root für maximale Sicherheit)
• HTTP Port: 3000 (intern) → 443 HTTPS (Traefik)
• SSH Port: 2222 (extern) → 22 (intern)
• Health Check: Aktiv und monitoring

PostgreSQL Container

• Image: postgres:17-alpine
• Größe: ~115 MB (sehr schlank)
• Health Check: pg_isready (30s interval)
• Nur auf gitea-backend Netzwerk

Deployment-Prozess: Lessons Learned

Phase 1: Vorbereitung & Passwörter

Kritische Erkenntnisse:

• 4 hochsichere Passwörter generiert (32-256 Zeichen)
• GITEA_SECRET_KEY ist unveränderbar nach Setup - muss sicher gespeichert werden!
• .env Datei muss 600 Berechtigungen haben (nur Owner kann lesen)

# Passwort-Generierung Best Practice
openssl rand -base64 32    # Standard passwords (32 chars)
openssl rand -hex 80       # Internal token (80 hex chars)

Phase 2: Authentik SSO Integration - Debugging Prozess

Das SSO Setup war komplex und erforderte mehrere Konfigurationsschritte zur Behebung von Fehlern.

Problem 1: Redirect URI Case Sensitivity

Root Cause: URLs sind case-sensitive!

• ❌ Authentik hatte: https://git.matzka.cloud/user/oauth2/authentik/callback (lowercase)
• ✅ Gitea sendete: https://git.matzka.cloud/user/oauth2/Authentik/callback (uppercase A)

Lösung: Authentik Provider URI auf korrektes Case aktualisiert.

Problem 2: Auto-Registration Disabled

Root Cause: GITEA__service__DISABLE_REGISTRATION: "true" war in docker-compose.yml gesetzt

Lösung:

1. OAuth2 Source Name auf "Authentik" (nicht "Authentik SSO") korrigiert
2. Auto-registration User Checkbox aktiviert

Finales SSO Setup

Einstellung	Authentik Provider	Gitea OAuth2
Name	Gitea OIDC Provider	Authentik
Type	OAuth2/OpenID Provider	OAuth2
Client ID	gitea	gitea
Redirect URI	https://git.matzka.cloud/user/oauth2/Authentik/callback
Scopes	openid, email, profile
Auto-register	-	✅ Enabled

Phase 3: Backup Integration

Gitea wurde in das bestehende Docker Volume Backup System integriert:

Backed Up Volumes:

• postgres_gitea_data - Datenbank (kritisch!)
• gitea_data - Repositories und User-Daten
• gitea_config - Konfigurationsdateien

Backup Strategie:

• Automatisches Backup täglich um 03:00 UTC
• 30-Tage Retention Policy
• Kompression: tar.gz (~2-6 MB pro Backup)
• Notifikationen via Mailcow

Funktionalität & Features

Git Operations (HTTPS & SSH)

HTTPS Clone:

git clone https://git.matzka.cloud/username/repo.git
cd repo
git add .
git commit -m "message"
git push origin main

SSH Clone:

git clone ssh://git@ssh2.matzka.cloud:2222/username/repo.git
# Oder: git clone git@ssh2.matzka.cloud:2222:username/repo.git

Beide Methoden sind vollständig funktional und unterstützen:

• ✅ Push/Pull mit Authentifizierung
• ✅ Large File Support
• ✅ Branch Management
• ✅ Tags und Releases

Email Notifications

Gitea sendet automatische Benachrichtigungen via Mailcow:

• Issue Notifications - Wenn Issues erstellt/aktualisiert werden
• Pull Request Notifications - Reviewer und Participants benachrichtigt
• Repository Notifications - Pushs, Releases, etc.

Email Konfiguration:

Setting	Value
SMTP Server	mail.matzka.cloud:587
Protocol	SMTP + STARTTLS
Auth User	gitea@matzka.cloud

Authentik SSO Single Sign-On

Nach erfolgreicher Konfiguration läuft SSO vollständig:

Login Flow:

1. User klickt "Sign In" auf Gitea
2. Wird zu Authentik Authentifizierung weitergeleitet
3. Nach erfolgreichem Login: Automatische Rückkehr zu Gitea
4. User wird automatisch registriert (falls neu)

Security Best Practices

Implementiert

Empfehlungen für Zukunft

• [ ] Regelmäßige Security Audits (quarterly)
• [ ] Log Monitoring Integration (ELK Stack)
• [ ] Rate Limiting für API (wenn öffentlich)
• [ ] Repository Signing Key Integration
• [ ] Branch Protection Rules nach Best Practices
• [ ] Regular Image Updates (Gitea & PostgreSQL)

Verwendung & Getting Started

Erste Schritte

1. Web UI öffnen: https://git.matzka.cloud
2. Mit Authentik anmelden (SSO)
3. Neues Repository erstellen (im Web UI)
4. Repository klonen:

   git clone https://git.matzka.cloud/username/repo.git
   cd repo

Best Practices für Git Workflows

Feature Branch Workflow

git checkout -b feature/new-feature
# Make changes
git add .
git commit -m "feat: description"
git push origin feature/new-feature
# Create Pull Request via Web UI

Semantic Versioning mit Tags

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

Troubleshooting Guide

SSO Login funktioniert nicht

Schritte:

1. Überprüfe Authentik Provider Redirect URI auf korrekte Case-Sensitivity
2. Verifiziere Discovery Endpoint: curl https://auth.matzka.cloud/application/o/gitea/.well-known/openid-configuration
3. Überprüfe Auto-register Checkbox in Gitea OAuth2 Source

HTTPS Zugriff funktioniert nicht

Schritte:

1. Überprüfe DNS: dig git.matzka.cloud
2. Überprüfe Traefik Logs: docker logs traefik
3. Überprüfe Gitea Container läuft: docker ps | grep gitea
4. Test Traefik Routing: curl -I https://git.matzka.cloud

SSH Git Operationen fehlgeschlagen

Schritte:

1. Test SSH Connection: ssh -vT -p 2222 git@ssh2.matzka.cloud
2. Überprüfe Port ist geöffnet: netstat -tuln | grep 2222
3. Überprüfe SSH Key ist in Gitea hinterlegt: Settings → SSH Keys
4. Falls Gitea neuer Container: SSH Keys könnten fehlen