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	Optional: Git-SSH zu Forgejo — nur nötig, wenn du Variante B in Schritt 5 nutzt

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 Regeln (ufw allow 22,80,443/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. 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/

Hinweis Git-SSH: Die Service-Vorlage bietet kein Port-Mapping in der UI an. Das ist okay — wir pushen standardmäßig über HTTPS (Schritt 5, Variante A), dafür braucht es keinen zusätzlichen Port. Wer trotzdem SSH will: Variante B in Schritt 5.

4. Deploy klicken. Danach https://git.deine-domain.de öffnen und die Ersteinrichtung durchgehen:
   • Datenbanktyp SQLite3, Pfad: /data/gitea/gitea.db (muss unter /data liegen — das ist das persistente Volume; Forgejo nutzt intern noch Gitea-Ordnernamen, das ist normal).
   • Server-Domain und Root-URL sind durch die Umgebungsvariablen schon korrekt vorausgefüllt.
   • 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) erreichbar ist (Git-SSH auf Port 2222 nur, falls du Variante B nutzt), ist die Angriffsfläche klein: kein offenes Web-Registrierungsformular, keine Passwort-Logins über SSH.

5. Repository anlegen und LeafItToMe pushen

In der Web-UI Neues Repository → Name leafittome → ohne README/Lizenz initialisieren (das Repo existiert lokal schon).

Variante A: HTTPS mit Zugriffs-Token (empfohlen — kein extra Port nötig)

1. In Forgejo: Einstellungen → Anwendungen → Zugriffstoken verwalten → Token erzeugen (Berechtigung repository: Lesen und Schreiben). Das Token wird einmalig angezeigt — direkt kopieren.
2. Auf dem Mac:

cd ~/Documents/Projekte/Planty
git remote add origin https://git.deine-domain.de/<dein-nutzer>/leafittome.git
git push -u origin main

3. Beim ersten Push fragt Git nach Zugangsdaten: Benutzername = dein Forgejo-Nutzer, Passwort = das Token (nicht dein Login-Passwort). macOS speichert es im Schlüsselbund — danach wirst du nie wieder gefragt.

Variante B: Git-SSH (nur wenn gewünscht)

Die Forgejo-Vorlage hat kein Port-Mapping in der Coolify-UI, aber jede Service-Vorlage ist eine bearbeitbare Docker-Compose-Datei: Im Service „Edit Compose File" öffnen und beim Forgejo-Container ergänzen:

    ports:
      - "2222:22"

Zusätzlich als Umgebungsvariablen FORGEJO__server__SSH_DOMAIN=git.deine-domain.de und FORGEJO__server__SSH_PORT=2222 setzen (für korrekte Clone-URLs), Port 2222 in der Hetzner-Firewall öffnen, Service neu deployen. Dann in Forgejo unter Einstellungen → SSH/GPG-Schlüssel den Inhalt von ~/.ssh/id_ed25519.pub hinterlegen und als Remote nutzen:

git remote add origin ssh://git@git.deine-domain.de:2222/<dein-nutzer>/leafittome.git

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

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 offen (2222 nur bei Git-SSH-Variante B) — 8000 und 3000 zu
• Forgejo-Zugriffstoken sicher verwahrt (macOS-Schlüsselbund), nicht in Dateien/Notizen
• 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