homelab/README.md

# 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).