Benjamin Weinlich 88c541c9ed docs(adr): mirror 6 ADRs from M7.1 into repo

Adds the Architecture Decision Records that were written during the
Forgejo deployment (M7.1) as part of moving docs from the iCloud folder
into this versioned repository.

Includes:
- ADR-0001: Forgejo vs Gitea (non-profit stewardship)
- ADR-0002: ai-apps placement (no separate VM)
- ADR-0003: Native OIDC, not ForwardAuth
- ADR-0004: Subdomain code.sdda.eu
- ADR-0005: Volume mount on /data (lesson learned)
- ADR-0006: Silent SSO via OAuth2 launch URL (lesson learned)

Plus a docs/adr/README.md that explains the ADR format, lists the
current ADRs, and provides a template for future entries.

Refs OP#1118

2026-04-11 22:26:05 +02:00

3.4 KiB

Raw Blame History

ADR-0002: Forgejo auf ai-apps, nicht auf separater VM

Status: Accepted Datum: 2026-04-11 Entscheider: Benjamin Weinlich Phase: M7.1 — Forgejo Deployment

Kontext

Forgejo kann überall laufen — auf einem eigenen Hetzner-Server, neben bestehenden Services, oder sogar on-prem. Wir müssen uns festlegen.

Optionen geprüft:

Auf ai-apps (Hetzner cx22) neben n8n, eh-search, locosoft, etc.
Auf Pegasus (Hetzner cx33) neben dem Electric-Horses Stack
Auf einem neuen separaten Hetzner cx22 nur für Forgejo
On-premises im Autohaus auf Hardware dort

Entscheidung

Auf ai-apps. Kein separater Server, kein Pegasus, kein on-prem.

Begründung

Warum ai-apps

Traefik 3.6.2 läuft schon dort mit Let's Encrypt Resolver. Keine neue TLS-Infrastruktur nötig.
Stack-Pattern etabliert (/opt/ai-apps/<name>/docker-compose.yml) — Forgejo reiht sich nahtlos ein.
Private-Network-Kommunikation mit anderen Services verfügbar (Mailcow, Authentik, etc.).
Ressourcen reichen: 7.6 GB RAM total, nach Verbrauch der bestehenden Services ~5.7 GB verfügbar (inkl. Cache). Forgejo + Postgres peak ~800 MB.
Operations-Pattern bekannt: Docker Compose, Portainer, Cron-Backups — alles schon da.

Warum nicht Pegasus

Pegasus hostet den öffentlichen Webseiten-Stack (Astro, Directus, MariaDB, Nginx, Qdrant). Das ist kunden-facing Production mit hohen Verfügbarkeitsanforderungen. Wir wollen keine zusätzliche Last oder Neuerungen dort. Pegasus hat außerdem kein public IPv4 — wir müssten über Webmin proxyn, was den Pfad unnötig verkompliziert.

Warum nicht separater Server

Ein neuer cx22 würde ~4.50 €/Monat kosten und zusätzlich eigenen Traefik, eigene Let's Encrypt Config, eigene Backup-Infra, eigene Monitoring-Integration erfordern. Für einen einzelnen Service mit <1 GB RAM-Bedarf ist der Ops-Overhead nicht gerechtfertigt. Re-evaluation: Sobald Forgejo Actions (CI/CD runners) aktiviert werden, wird der Ressourcenbedarf steigen und ein Upgrade auf cx32 oder ein separater Runner-Host Sinn machen.

Warum nicht on-prem

Git-Hosting muss 24/7 von außen erreichbar sein (Home-Office, Mobil, von überall). Das Autohaus-LAN ist hinter Consumer-Internet und hat keinen stabilen Public-Pfad. Außerdem steht der on-prem Stack (Loco-Soft-Server, eh-sync Bridge) unter anderen Verfügbarkeitsbedingungen.

Konsequenzen

Positiv

Schnelles Deployment (keine neue Infrastruktur)
Keine Extra-Kosten
Integration mit Authentik via Private Network (10.0.0.x)
Konsolidiertes Monitoring (alle Stacks via Portainer sichtbar)

Negativ / Risiko

RAM-Druck: Bei ~250 MB wirklich freiem RAM ist der Spielraum knapp. Forgejo + Postgres peak ~800 MB kommt nah an die Obergrenze. Mitigation: Monitoring, ggf. Upgrade auf cx32 (16 GB, +4 €/Monat) wenn nötig.
Single-Point-of-Failure ai-apps: Wenn ai-apps ausfällt, sind n8n, eh-search, locosoft und Forgejo gleichzeitig weg. Mitigation: Hetzner Cloud Snapshots, Docker Volume Backups.
Keine CI-Runner möglich: Forgejo Actions würde ai-apps sprengen. Wenn CI dazu kommt, separater Runner-Host (z.B. Woodpecker auf cx22).

Re-evaluation-Trigger

RAM-Nutzung auf ai-apps dauerhaft > 85%
Wunsch nach Forgejo Actions / CI-Runnern
Mehrere gleichzeitige große Git-Pushes verlangsamen andere Services spürbar

In diesen Fällen: Separater Hetzner-Server für Forgejo (oder cx32-Upgrade von ai-apps).

3.4 KiB Raw Blame History