From 3085b51a48389755ae7a52da34c8744ce7febf1b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 30 Jul 2026 15:56:36 +0200
Subject: [PATCH] README: Betriebswissen dokumentieren

Unumstoessliche Regeln (Projektname, Volumes, kein Gitea-Downgrade, kein
Portainer mehr), Deploy- und Erst-Deploy-Ablauf, Runner-Registrierung,
Backup/Restore inkl. Off-Host-Hinweis.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3550294
--- /dev/null
+++ b/README.md
@@ -0,0 +1,97 @@
+# thread-net-git — Traefik + Gitea + cAdvisor + Actions-Runner (CFGMON)
+
+Infrastruktur-Repo für den Kern-Stack auf dem Operating-Host (CFGMON,
+`rohana.axion1337.de`). Abgelöst aus dem unversionierten Portainer-Stack
+(Stack-ID 8) am 2026-07-30 — siehe Backlog CFGMON-02.
+
+| Dienst | Image | Zweck |
+|---|---|---|
+| reverse-proxy | traefik:v3.7.9 | TLS-Terminierung für ALLE Dienste des Hosts (auch Grafana aus dem monitoring-Stack) |
+| gitea | gitea/gitea:1.27.0 | Git-Hosting, `rohana.axion1337.de` |
+| cadvisor | cadvisor:v0.49.1 | Container-Metriken für Prometheus (monitoring-Stack) |
+| runner | gitea/act_runner:0.6.1 | Gitea-Actions-Runner `builder-1` (Labels: `linux-build`, `win-wine`) |
+
+## Unumstößliche Regeln
+
+1. **Projektname `thread-net-git` nie ändern** (`name:` in der Compose).
+   Das Gitea-Datenvolumen heißt `thread-net-git_gitea-data` und ist als
+   `external` deklariert — bei falschem Namen bricht der Deploy laut ab.
+2. **Volumes `thread-net-git_gitea-data` und `thread-net-git_letsencrypt`
+   niemals löschen.** Ersteres sind die Produktivdaten (Repos, SQLite-DB,
+   LFS, SSH-Hostkeys), letzteres enthält `acme.json` — eine Zertifikats-
+   Neuausstellung scheitert an der Firewall (80/443 nur für User-IP offen).
+3. **Gitea nie auf eine ältere Version pinnen** — SQLite-Schema kennt kein
+   Downgrade. Upgrades: Minor-Schritte, vorher Backup (s.u.).
+4. **Diesen Stack nie wieder über Portainer anfassen.** Portainer
+   identifiziert Ressourcen über den Compose-Projektnamen; ein „Stack
+   löschen" dort würde die laufenden Container entfernen.
+
+## Deploy
+
+```bash
+cd /opt/thread-net-git
+docker network create traefik   # falls noch nicht vorhanden
+docker compose up -d
+```
+
+Erst-Deploy auf frischem Host (letsencrypt-Volume noch leer):
+
+```bash
+docker compose up --no-start          # legt Volumes/Container an
+# acme.json aus Backup einspielen (Rechte 600, root:root):
+docker run --rm -v thread-net-git_letsencrypt:/dst -v /opt/backup:/src alpine \
+  sh -c 'cp /src/acme-<datum>.json /dst/acme.json && chmod 600 /dst/acme.json'
+docker compose up -d
+```
+
+## Runner
+
+Erstregistrierung (einmalig, Identität landet danach in `runner-data/.runner`):
+
+```bash
+cp .env.example .env
+docker exec -u git thread-net-git-gitea-1 gitea actions generate-runner-token
+# Token in .env als RUNNER_TOKEN eintragen, dann:
+docker compose up -d runner
+# Registrierung prüfen (Admin-UI → Actions → Runners), danach .env leeren.
+```
+
+Job-Labels: `linux-build` (electronuserland/builder:22) und `win-wine`
+(electronuserland/builder:wine, Windows-Cross-Builds). Kapazität 1,
+Job-Container limitiert auf 2,2 GiB / 1,5 CPUs (`runner/config.yaml`) —
+der Host hat nur 2 Kerne / 3,7 GiB ohne Swap.
+
+Job-Container erreichen `rohana.axion1337.de` über das Docker-Host-Gateway
+(`extra_hosts` + `--add-host` in den Container-Options) — das umgeht die
+Cloud-Firewall, ohne die Zertifikatsprüfung zu brechen.
+
+## Backup & Restore
+
+Warm-Backup (laufender Betrieb, nächtlich per Cron des Users `rantanplan`):
+
+```bash
+docker exec -u git -w /tmp thread-net-git-gitea-1 \
+  gitea dump -c /data/gitea/conf/app.ini -f /tmp/gitea-dump.zip
+docker cp thread-net-git-gitea-1:/tmp/gitea-dump.zip /opt/backup/gitea-dump-$(date +%F).zip
+docker exec thread-net-git-gitea-1 rm /tmp/gitea-dump.zip
+```
+
+Restore auf frischem Host: Volume `thread-net-git_gitea-data` anlegen,
+Dump-Zip entpacken (`gitea-repo.zip` → `/data/git/repositories`,
+`gitea-db.sql` importieren bzw. `gitea.db` aus `data/` übernehmen,
+`app.ini` nach `/data/gitea/conf/`), dann Stack deployen. Details:
+https://docs.gitea.com/administration/backup-and-restore
+
+**Off-Host-Kopie nicht vergessen** — ein Backup auf demselben Host schützt
+nicht vor Plattenverlust:
+`scp -P 2248 rantanplan@188.245.193.243:/opt/backup/gitea-dump-<datum>.zip .`
+
+## Bezüge
+
+- Monitoring-Stack (Grafana/Prometheus/Loki): Repo `sorb/threadnet-operating`,
+  Checkout `/opt/threadnet-operating`. Prometheus scrapt `cadvisor:8080` und
+  `traefik:8080` aus diesem Stack über das gemeinsame externe `traefik`-Netz.
+- Backlog: Repo `sorb/Backlogs` (`hosts/cfgmon.md`).
+- Gitea-Konfiguration (`app.ini` mit Secrets) liegt bewusst NICHT im Repo,
+  sondern nur im Datenvolumen; Änderungen via `GITEA__section__KEY`-Env-Vars
+  in der Compose.