From 551bad1569ddb4f09404aaf683adf5d7996b40c3 Mon Sep 17 00:00:00 2001
From: claude <claude@core.bob>
Date: Tue, 2 Jun 2026 08:43:02 +0000
Subject: [PATCH] Add comprehensive README

---
 README.md | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 202 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e8580f4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,202 @@
+# homelab
+
+Infrastruktur als Code für das Heimnetz. Alle Services laufen containerisiert auf **corebob** und werden über **Traefik** als Reverse Proxy erreichbar gemacht. Dieses Repository enthält alle Docker-Compose-Konfigurationen und wird automatisch auf `gitea.basti.badana.de` gespiegelt.
+
+---
+
+## Architektur
+
+```
+Internet
+    │
+    ▼
+┌─────────────────────┐
+│  öffentliche VM      │  traefik.basti.badana.de
+│  Traefik + Gitea     │  gitea.basti.badana.de
+│  Let's Encrypt TLS   │
+└─────────────────────┘
+         ▲
+         │ Push-Mirror (bei jedem Commit)
+         │
+┌─────────────────────┐
+│  corebob             │  192.168.178.113
+│  Ubuntu 26.04 LTS    │  16 Kerne, 15 GB RAM, 98 GB Disk
+│  Docker + Traefik    │
+│  Interne Services    │
+└─────────────────────┘
+         ▲
+         │ DNS (*.core.bob → 192.168.178.113)
+         │
+┌─────────────────────┐
+│  bobhole (Pi-hole)   │
+│  DNS für core.bob    │
+└─────────────────────┘
+```
+
+### Netzwerk
+
+| Host | Domain | Zweck |
+|------|--------|-------|
+| corebob | `*.core.bob` | Interne Services, nur im Heimnetz erreichbar |
+| öffentliche VM | `*.basti.badana.de` | Extern erreichbare Services |
+
+---
+
+## Services
+
+### corebob (intern)
+
+| Service | URL | Compose |
+|---------|-----|---------|
+| Traefik Dashboard | https://traefik.core.bob/dashboard/ | `traefik/` |
+| Gitea | https://gitea.core.bob | `gitea/` |
+
+### Öffentliche VM
+
+| Service | URL | Compose |
+|---------|-----|---------|
+| Traefik Dashboard | https://traefik.basti.badana.de | `traefik-public/` |
+| Gitea (Mirror) | https://gitea.basti.badana.de | `gitea-public/` |
+
+---
+
+## Verzeichnisstruktur
+
+```
+homelab/
+├── traefik/                  # Traefik auf corebob
+│   ├── docker-compose.yml
+│   ├── traefik.yml           # Statische Konfiguration
+│   └── dynamic-tls.yml       # TLS-Zertifikat (mkcert)
+├── gitea/                    # Gitea auf corebob
+│   └── docker-compose.yml
+├── traefik-public/           # Traefik auf öffentlicher VM
+│   └── docker-compose.yml
+├── gitea-public/             # Gitea auf öffentlicher VM
+│   └── docker-compose.yml
+└── README.md
+```
+
+> **Nicht im Repository** (gitignore): `certs/`, `.mkcert-ca/`, `data/`  
+> Zertifikate und persistente Service-Daten werden nicht versioniert.
+
+---
+
+## TLS / Zertifikate
+
+### corebob (intern, mkcert)
+
+Interne Services nutzen eine selbst signierte CA, erstellt mit [mkcert](https://github.com/FiloSottile/mkcert).
+
+```
+CA-Root:      ~/traefik/.mkcert-ca/rootCA.pem
+Zertifikat:   ~/traefik/certs/core.bob.crt
+Key:          ~/traefik/certs/core.bob.key
+Gültig für:   core.bob, *.core.bob
+Läuft ab:     September 2028
+```
+
+Die Root-CA muss einmalig auf jedem Client-Gerät installiert werden:
+
+```bash
+# Arch Linux (Chromium/System):
+sudo cp rootCA.pem /etc/ca-certificates/trust-source/anchors/rootCA-corebob.crt
+sudo update-ca-trust
+
+# Ubuntu/Debian:
+sudo cp rootCA.pem /usr/local/share/ca-certificates/rootCA-corebob.crt
+sudo update-ca-certificates
+
+# Firefox/Librewolf:
+# about:preferences#privacy → Zertifikate anzeigen → Importieren
+```
+
+### Öffentliche VM (Let's Encrypt)
+
+Traefik holt automatisch Zertifikate via ACME TLS-Challenge. Keine manuelle Konfiguration nötig.
+
+---
+
+## DNS
+
+Pi-hole auf **bobhole** liefert Wildcard-DNS für `*.core.bob`:
+
+```
+# /etc/dnsmasq.d/core.bob.conf
+address=/core.bob/192.168.178.113
+```
+
+Pi-hole v6 erfordert `etc_dnsmasq_d = true` in `/etc/pihole/pihole.toml`.
+
+---
+
+## Neuen Service hinzufügen
+
+### Auf corebob
+
+1. Verzeichnis anlegen: `mkdir ~/homelab/<service>`
+2. `docker-compose.yml` erstellen mit diesen Traefik-Labels:
+
+```yaml
+services:
+  myservice:
+    image: ...
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.myservice.rule=Host(`myservice.core.bob`)"
+      - "traefik.http.routers.myservice.entrypoints=websecure"
+      - "traefik.http.routers.myservice.tls=true"
+      - "traefik.http.services.myservice.loadbalancer.server.port=<PORT>"
+    networks:
+      - traefik
+
+networks:
+  traefik:
+    external: true
+```
+
+3. Service starten: `cd ~/homelab/<service> && docker compose up -d`
+4. Ins Repo committen und pushen:
+
+```bash
+cd ~/homelab
+git add <service>/
+git commit -m "Add <service>"
+git push
+```
+
+Der Push-Mirror synchronisiert automatisch auf `gitea.basti.badana.de`.
+
+### Auf der öffentlichen VM
+
+Gleiche Struktur, aber:
+- Netzwerk: `proxy` statt `traefik`
+- Kein `tls=true` Label nötig (Let's Encrypt greift automatisch via `myresolver`)
+
+---
+
+## Docker-Netzwerke
+
+| Netzwerk | Wo | Zweck |
+|----------|----|-------|
+| `traefik` | corebob | Verbindet alle internen Services mit Traefik |
+| `proxy` | öffentliche VM | Verbindet alle externen Services mit Traefik |
+
+Netzwerke einmalig anlegen falls nicht vorhanden:
+```bash
+docker network create traefik   # corebob
+docker network create proxy     # öffentliche VM
+```
+
+---
+
+## Gitea-Mirror
+
+Das Repository wird bei jedem Commit automatisch gespiegelt:
+
+| | URL |
+|-|-----|
+| **Primär** | https://gitea.core.bob/claude/homelab |
+| **Mirror** | https://gitea.basti.badana.de/claude/homelab |
+
+Mirror-Intervall: 8 Stunden (zusätzlich sync bei jedem Push).