# README.md

## Übersicht

Dieses Projekt beschreibt den Betrieb einer selbstgehosteten Gitea-Instanz in Docker Compose, verwaltet über Portainer Community Edition. Die Instanz verwendet ein Host-Bind-Mount für `/data`, SQLite als Datenbank und einen dedizierten Container-Namen (`forgejo`), wodurch Backups und Restore auf Host-Ebene einfach umsetzbar sind.

## Architektur

Der Stack besteht aus einem einzelnen Gitea-Container auf Basis von `gitea/gitea:latest`, der die Weboberfläche auf Port 3000 und SSH für Git-Zugriffe auf Port 922 veröffentlicht. Die persistenten Daten liegen im Host-Verzeichnis `/home/hans/forgejo/data`, das in den Container nach `/data` gemountet wird.

| Komponente | Wert |
|---|---|
| Orchestrierung | Docker Compose |
| Verwaltung | Portainer Community Edition |
| Container-Name | `forgejo` |
| Service-Name | `server` |
| Image | `gitea/gitea:latest` |
| Datenbank | SQLite |
| Persistenz | Bind-Mount `/home/hans/forgejo/data:/data` |
| HTTP | `3000:3000` |
| SSH | `922:22` |

## Verzeichnisstruktur

Eine saubere Host-Struktur vereinfacht Betrieb, Backup und Migration. Für dieses Setup bietet sich folgende Struktur an:

```text
/home/hans/forgejo/
├── docker-compose.yml
├── .env
├── secrets/
│   └── smtp_password.txt
└── data/
```

Zusätzlich sollte ein separates Backup-Ziel außerhalb des Live-Datenpfads verwendet werden:

```text
/backup/gitea/
```

## Start und Betrieb

Der Stack kann direkt per Compose oder über Portainer Stacks verwaltet werden. Für einen CLI-basierten Betrieb sind die üblichen Compose-Befehle ausreichend.

```bash
docker compose pull
docker compose up -d
docker compose logs -f
```

Wenn Portainer verwendet wird, sollte Portainer nur als Verwaltungsoberfläche dienen, während Automatisierung wie Backups, Rotation und Offsite-Sync weiterhin hostseitig per Cron oder Systemd Timer läuft.[web:40]

## Backup

Für Gitea in Docker ist `gitea dump` die offizielle Backup-Methode. Laut Gitea-Dokumentation enthält der Dump Datenbank, Repositories, Konfiguration und weitere relevante Instanzdaten in einem Archiv.[web:1]

In diesem Projekt wird Portainer Community Edition ohne Business-Features verwendet. Da CE keine nativen Scheduled Tasks wie die Business Edition bereitstellt, sollte das Backup per Host-Cronjob umgesetzt werden.[web:40]

### Manueller Dump

```bash
docker exec -u git -w /data forgejo   /app/gitea/gitea dump -c /data/gitea/conf/app.ini   --file /data/gitea-dump-$(date +%Y%m%d-%H%M).zip
```

### Automatisierung

Die empfohlene operative Dokumentation liegt in der beigefügten Backup-Anleitung.

[code_file:42]

## Restore

Ein Restore erfolgt manuell durch Stoppen des Containers, Entpacken des Dumps und Zurückkopieren der Daten in das Host-Verzeichnis. Laut Gitea-Dokumentation sollten nach dem Restore die Git-Hooks neu generiert werden, damit Repository-Operationen wieder sauber funktionieren.[web:1]

## Sicherheit

In produktionsnahen Setups sollten keine Secrets im Klartext in der Compose-Datei stehen. Für SMTP- oder andere Zugangsdaten sind `.env` mit restriktiven Rechten oder Docker-Secrets die bessere Wahl als direkte Environment-Werte in der Stack-Datei.

Außerdem sollte das Projekt nicht dauerhaft auf `gitea/gitea:latest` laufen. Für reproduzierbare Deployments sind feste Versionstags und ein geplanter Update-Prozess die robustere Variante.

## Betriebsempfehlungen

- SSH nur mit Schlüsseln erlauben und keinen Root-Login per SSH zulassen.
- Portainer nur per HTTPS und mit starkem Zugangsschutz betreiben.[web:40]
- Backups regelmäßig auf Restore testen.[web:1]
- Backups zusätzlich offsite sichern, etwa per rsync auf NAS oder auf S3-kompatiblen Storage.
- Updates von Ubuntu, Docker Engine und Container-Images geplant und nachvollziehbar durchführen.

## Nächste Schritte

Für den weiteren Ausbau dieses Projekts sind folgende Punkte sinnvoll:

- `.env` und Secrets aus der Compose-Datei auslagern.
- `latest` durch einen festen Gitea-Versionstag ersetzen.
- Cronjob oder Systemd-Timer für Backups einrichten.
- Optional Offsite-Backup per rsync oder rclone ergänzen.
- Reverse Proxy und TLS für externen Zugriff ergänzen.