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:

```bash
# 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:**

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

## 2. Coolify installieren und absichern

Falls Coolify noch nicht läuft:

```bash
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:

```bash
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:

```yaml
    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:

```bash
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