leafittome/docs/git-forgejo.md

Git-Hosting: Forgejo über Coolify auf dem Hetzner-VPS

Forgejo ist ein leichtgewichtiger, quelloffener Git-Server mit Web-Oberfläche (Fork von Gitea) — wie ein privates GitHub auf deinem Server. Coolify ist eine selbst gehostete Deployment-Plattform: Dienste wie Forgejo werden per Vorlage angelegt, Coolify kümmert sich um Docker, Reverse-Proxy, HTTPS-Zertifikate und Backups — statt handgepflegter docker-compose.yml-Dateien.

Da der Server öffentlich im Internet steht, gehört die Absicherung fest zur Einrichtung — sie ist in jedem Schritt mit eingebaut, plus eine Checkliste am Ende.

---

0. Voraussetzungen

• Hetzner-VPS mit Ubuntu/Debian, Root- bzw. sudo-Zugang per SSH
• Eine Domain, deren DNS du verwalten kannst. Lege zwei A-Records auf die VPS-IP an:
  • coolify.deine-domain.de → Coolify-Dashboard
  • git.deine-domain.de → Forgejo
• Mindestens ~2 GB RAM frei (Coolify selbst braucht ~1 GB; Forgejo ist genügsam)

1. Server-Grundabsicherung (vor allem anderen)

SSH härten — Anmeldung nur per Schlüssel, nie per Passwort:

# Auf dem Mac: öffentlichen Schlüssel anzeigen (falls keiner existiert: ssh-keygen -t ed25519)
cat ~/.ssh/id_ed25519.pub
# Auf dem VPS in ~/.ssh/authorized_keys eintragen (falls noch nicht geschehen)

Dann auf dem VPS in /etc/ssh/sshd_config prüfen/setzen und sudo systemctl restart ssh:

PasswordAuthentication no
PermitRootLogin prohibit-password

Wichtig: Teste in einem zweiten Terminal, dass der SSH-Login noch funktioniert, bevor du das erste schließt.

Firewall — am einfachsten die Hetzner Cloud Firewall (Cloud Console → Firewalls), sie greift schon vor dem Server. Eingehend nur:

Port	Protokoll	Zweck
22	TCP	SSH zum Server (Administration)
80	TCP	HTTP (nur für Let's-Encrypt-Zertifikate und Umleitung auf HTTPS)
443	TCP	HTTPS (Coolify-Proxy: alle Web-Oberflächen)
2222	TCP	Git-SSH zu Forgejo (git push/pull)

Alles andere bleibt zu — insbesondere 8000 (Coolify-Dashboard, siehe Schritt 2) und 3000 (Forgejo-Weboberfläche; sie läuft nur intern hinter dem Proxy). Alternativ ohne Cloud Firewall: ufw mit genau diesen vier Regeln (ufw allow 22,80,443,2222/tcp && ufw enable).

Updates automatisieren:

sudo apt install unattended-upgrades && sudo dpkg-reconfigure -plow unattended-upgrades

2. Coolify installieren und absichern

Falls Coolify noch nicht läuft:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

Direkt nach der Installation ist das Dashboard unter http://<vps-ip>:8000 erreichbar — öffne es sofort und lege den Admin-Account an (wer zuerst kommt, ist Admin!). Falls Port 8000 durch die Firewall aus Schritt 1 schon zu ist: Port kurz für deine eigene IP freigeben, Account anlegen, wieder schließen.

Dann absichern:

1. Eigene Domain fürs Dashboard: In Coolify → Settings → Instance Domain → https://coolify.deine-domain.de eintragen. Coolify holt automatisch ein Let's-Encrypt-Zertifikat; das Dashboard läuft ab dann verschlüsselt über Port 443.
2. Port 8000 endgültig schließen (Firewall-Regel entfernen bzw. gar nicht erst anlegen).
3. Registrierung deaktivieren: Settings → „Registration Enabled" ausschalten — sonst kann sich jeder im Internet einen Account auf deinem Coolify anlegen.
4. Zwei-Faktor-Authentifizierung für deinen Account aktivieren (Profil → Two-factor Authentication).

3. Forgejo als Coolify-Service anlegen

1. In Coolify: Projects → dein Projekt → + New → Service → in der Vorlagen-Liste Forgejo wählen (Variante mit SQLite reicht für einen Einzelnutzer völlig; Postgres wäre Overkill).
2. Im Service unter Domains für den Web-Container https://git.deine-domain.de eintragen → HTTPS-Zertifikat kommt automatisch.
3. Git-SSH-Port freischalten: Im Service unter Ports Mappings den Container-Port 22 auf Host-Port 2222 mappen (Eintrag 2222:22). Ohne dieses Mapping funktioniert nur HTTPS-Klonen — auch okay, aber SSH ist bequemer.
4. Umgebungsvariablen (Environment Variables) des Forgejo-Containers ergänzen — so ist Forgejo schon beim ersten Start korrekt konfiguriert:

FORGEJO__service__DISABLE_REGISTRATION=true   # niemand außer dir kann Accounts anlegen
FORGEJO__server__DOMAIN=git.deine-domain.de
FORGEJO__server__ROOT_URL=https://git.deine-domain.de/
FORGEJO__server__SSH_DOMAIN=git.deine-domain.de
FORGEJO__server__SSH_PORT=2222                # damit angezeigte Clone-URLs den richtigen Port enthalten

5. Deploy klicken. Danach https://git.deine-domain.de öffnen → Ersteinrichtung bestätigen (die Werte sind durch die Variablen schon richtig) → Admin-Konto anlegen.

4. Forgejo absichern

• 2FA aktivieren: Einstellungen → Sicherheit → Zwei-Faktor-Authentifizierung (z. B. mit derselben Authenticator-App wie für Coolify).
• Kontrolle Registrierung: Site Administration → Configuration — „Registrierung deaktiviert" muss aktiv sein (kommt aus der Umgebungsvariable).
• Da Forgejo nur über den Coolify-Proxy (HTTPS) und Port 2222 (Git-SSH mit Schlüssel) erreichbar ist, ist die Angriffsfläche damit klein: kein offenes Web-Registrierungsformular, keine Passwort-Logins über SSH.

5. SSH-Schlüssel hinterlegen und Planty pushen

In Forgejo: Einstellungen → SSH/GPG-Schlüssel → Inhalt von ~/.ssh/id_ed25519.pub (vom Mac) einfügen.

Dann in der Web-UI Neues Repository → Name planty → ohne README/Lizenz initialisieren (das Repo existiert lokal schon). Auf dem Mac:

cd ~/Documents/Projekte/Planty
git remote add origin ssh://git@git.deine-domain.de:2222/<dein-nutzer>/planty.git
git push -u origin main

Ab dann genügt nach jedem Arbeitsstand ein git push. Test: Die Dateien erscheinen unter https://git.deine-domain.de/<dein-nutzer>/planty.

6. Backups

Zwei Ebenen, beide einrichten:

1. Hetzner-Snapshots/Backups: In der Hetzner Cloud Console automatische Server-Backups aktivieren (kostet ~20 % des Serverpreises, sichert den ganzen Server inkl. Coolify und aller Dienste).
2. Forgejo-Daten gezielt: Die Forgejo-Daten liegen in einem Docker-Volume (in Coolify unter Storages des Services einsehbar). Nimm dieses Verzeichnis in dein bestehendes Backup auf dem VPS auf, falls du dort schon etwas wie restic/borg nutzt.

Zusammen mit dem lokalen Klon auf deinem Mac existieren damit immer mindestens drei Stände des Codes.

7. Aktuell halten

• Coolify: zeigt verfügbare Updates im Dashboard an → einspielen.
• Forgejo: im Service das Image-Tag aktualisieren (bzw. Pull latest image + Redeploy). Forgejo veröffentlicht Sicherheits-Releases; einmal im Monat nachschauen genügt.
• Betriebssystem: erledigt unattended-upgrades aus Schritt 1.

---

Sicherheits-Checkliste (zum Abhaken)

• SSH: nur Schlüssel-Login, kein Passwort-Login, Root-Login nur mit Schlüssel
• Firewall aktiv: nur 22, 80, 443, 2222 offen — 8000 und 3000 zu
• Coolify: eigene HTTPS-Domain, Registrierung aus, 2FA aktiv
• Forgejo: Registrierung aus, 2FA für Admin aktiv, nur hinter HTTPS erreichbar
• Automatische Betriebssystem-Updates aktiv
• Hetzner-Backups oder Snapshots aktiv
• SSH-Login vom Mac auf Server und git push einmal erfolgreich getestet