Doku erstellt

README.md

@@ -0,0 +1,98 @@
+# 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.