rd13_tile_server/docs/history/summary/PROJECT_CONTEXT.md

# PROJECT_CONTEXT – rd13_tile_server

**Letzte Aktualisierung:** 2026-06-13 – Stack vollständig in Betrieb: Martin + tileserver-gl + Caddy. Kartographer-PNG-Tiles öffentlich erreichbar und verifiziert.

---

## Projektziel

Selbst gehosteter Tile Server für MediaWiki (Kartographer), Nextcloud, Home Assistant.
**Stack:** Martin (Vektor-API) + tileserver-gl (Raster PNG) + Caddy (Reverse Proxy).
Tile-Updates manuell 2–4×/Jahr; Styles anpassbar.

---

## Stack (Architektur ADR-001)

- **Vektor-API:** `ghcr.io/maplibre/martin:latest` (Port 9982 → `/osm/{z}/{x}/{y}`)
- **Raster-Renderer:** `maptiler/tileserver-gl` (Port 9983 → `/styles/osm-intl/{z}/{x}/{y}.png`)
- **Proxy:** Caddy (`rd13_system_proxy`) – SSL via Let's Encrypt, Routing `/styles/` → 9983, rest → 9982
- **Konfiguration:** `config/tileserver.json` (tileserver-gl), `config/styles/osm-intl.json` (MapLibre GL Style)
- **Daten:** `/data/` – osm.mbtiles, fonts/, sprites/
- **Git Remote:** `ssh://git@192.168.178.6:2222/cschulz/rd13_tile_server.git`

---

## Architektur-Decision: Martin + tileserver-gl

**Rationale:** [siehe ADR-001](../../docs/adr/001-martin-tileserver-gl-stack.md)

| Komponente | Rolle | Input | Output |
|---|---|---|---|
| Martin | Vektor-Tile-API | osm.mbtiles | `/osm/{z}/{x}/{y}.pbf` |
| tileserver-gl | Raster-Renderer | Martin PBF + Styles | `/osm-intl/{z}/{x}/{y}.png` |
| NPM | Proxy + Rate Limit | Requests | HTTPS mit Cache-Headers |

**Kartographer-URL bleibt gleich:**
- `$wgKartographerMapServer = 'https://tiles.rd13server.de'`
- Style `osm-intl` (Raster)

---

## Aktueller Zustand

### Laufende Services
- Martin-Container: **laeuft** und ist **healthy**
- WebUI: **aktiviert** ueber `--webui enable-for-all`

### Vorhandene Daten in `/data/`
| Datei/Ordner | Status |
|---|---|
| `osm.mbtiles` | ✅ wird von Martin erkannt (Source `osm`) |
| `fonts/` | ✅ installiert |
| `styles/` | ✅ vorhanden |
| `satellite.mbtiles` | ❌ noch nicht heruntergeladen |

### Git-Stand
- Branch: `main`
- Letzter Commit: `46ac204` – tileserver-gl operational, config in config/

---

## Aktueller Zustand (2026-06-13) – VOLLSTÄNDIG IN BETRIEB ✅

| Endpunkt | Status | Antwort |
|---|---|---|
| `https://tiles.rd13server.de/styles/osm-intl/{z}/{x}/{y}.png` | ✅ 200 | PNG 256×256 |
| `https://tiles.rd13server.de/osm/{z}/{x}/{y}` (PBF) | ✅ 200 | application/x-protobuf |
| `https://tiles.rd13server.de/health` | ✅ 200 | OK |
| `rd13_tileserver` Container | ✅ healthy | Port 9983 |
| `rd13_martin` Container | ✅ healthy | Port 9982 |
| Caddy Proxy (`rd13_system_proxy`) | ✅ aktiv | server: Caddy |

**MediaWiki Kartographer Config:**
- `$wgKartographerMapServer = 'https://tiles.rd13server.de/styles'`
- `$wgKartographerDfltStyle = 'osm-intl'`
- → Request-URL: `https://tiles.rd13server.de/styles/osm-intl/{z}/{x}/{y}.png` ✅

---

## Nächste Schritte


## Offene Aufgaben

## Bekannte Fallstricke

- `data/tmp/` und `data/sources/` werden von Docker als `root` erstellt → `sudo rm -rf` nötig
- Planetiler braucht sehr viel Disk (87 GB sources + 264 GB tmp + ~70 GB output = ~420 GB)
  → **Nicht mehr nötig**, wir nutzen OpenFreeMap MBTiles direkt
- Fish Shell unterstützt kein heredoc `<< 'EOF'` → Python `open().write()` oder `tee` verwenden
- Download von OpenFreeMap: `wget --continue` für Resume-Support bei Abbruch

---

## Erledigte Aufgaben

- [x] Git-Repo initialisiert und auf Forgejo gepusht
- [x] Martin WebUI aktiviert (`--webui enable-for-all`)
- [x] Endpunkte verifiziert (`/health`, `/catalog`, Root 200)
- [x] MediaWiki-Kartographer Doku + LocalSettings konfiguriert
- [x] ADR-001: Martin + tileserver-gl Stack-Entscheidung dokumentiert
- [x] **tileserver-gl** Service in docker-compose.yml (Port 9983, `maptiler/tileserver-gl`)
- [x] `config/tileserver.json` – Service-Konfiguration (MBTiles + Styles + Fonts)
- [x] `config/styles/osm-intl.json` – MapLibre GL Style für Raster-Rendering
- [x] Caddy-Routing: `/styles/osm-intl/*` → Port 9983, rest → Port 9982
- [x] **End-to-End verifiziert:** PNG-Tiles 200 bei Zoom 0/5/10/14

---

## Offene Aufgaben

- [ ] **MediaWiki in Browser testen** – mapframe/maplink auf einer Wiki-Seite
- [ ] **REQ-002 Rate Limiting** – Caddy-seitig absichern (rd13_system_proxy)
- [ ] **REQ-002 Rate Limiting** – NPM Advanced Config für `tiles.rd13server.de`
- [ ] NPM Proxy-Host für `tiles.rd13server.de` anlegen (manuell im NPM UI)
- [ ] fail2ban optional konfigurieren (REQ-002 Schicht 3)
- [ ] Satellit-Download (optional, REQ-005)
- [ ] Martin mit Satellit-Daten testen