rd13_tile_server/docs/history/summary/PROJECT_CONTEXT.md

# PROJECT_CONTEXT – rd13_tile_server

**Letzte Aktualisierung:** 2026-06-12 – Architektur-Entscheidung: Martin + tileserver-gl für Vektor + Raster. ADR-001 dokumentiert. PNG-Rendering für Kartographer nun planbar.

---

## Projektziel

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

---

## Stack (Architektur ADR-001)

- **Vektor-API:** `ghcr.io/maplibre/martin:latest` (Port 9982 extern → 3000 intern)
- **Raster-Renderer:** `ghcr.io/maptiler/tileserver-gl` (NEU – Port 8080 lokal, via NPM zu `/osm-intl`)
- **Proxy:** NPM (Nginx Proxy Manager) extern – SSL-Termination, Rate Limiting
- **Daten:** `/data/` – osm.mbtiles (Vektor), fonts/, styles/ (Rendering-Definitionen)
- **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: `0a5f6cd` - WebUI aktiviert und MediaWiki-Integration vorbereitet
- Noch offen (lokal): `docs/mediawiki-config.php`

---

## Nächste Schritte (Sprint 2026-06-19)

**Ziel:** Kartographer rendert PNG statt PBF-Vektor

1. **docker-compose.yml erweitern**
   - tileserver-gl Service hinzufügen (ghcr.io/maptiler/tileserver-gl)
   - Mount `/data/styles/`, `/data/fonts/`, `/data/sprites/`
   - Port: 8080 lokal (nur intern, nicht exposed)

2. **Style osm-intl vorbereiten**
   - Baseline MapLibre GL Style (JSON) in `/data/styles/osm-intl.json`
   - Quelle: Martin PBF unter `http://martin:3000/osm`
   - Fonts: `/fonts/`, Sprites: `/sprites/`

3. **NPM Proxy-Routing konfigurieren**
   - `/osm-intl/{z}/{x}/{y}.png` → http://tileserver-gl:8080/...
   - `/osm-intl/{z}/{x}/{y}@2x.png` → http://tileserver-gl:8080/...@2x
   - Cache-Headers: `max-age=86400`

4. **MediaWiki LocalSettings testen**
   - mapframe sollte jetzt PNG-Karten zeigen statt Fehler
   - Probe: https://tiles.rd13server.de/osm-intl/0/0/0.png

5. **REQ-002 Rate Limiting** (aus REQUIREMENTS.md)
   - NPM Advanced Config: limit_req_zone, limit_conn_zone, 429 status

---

## 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] Migration TileServer-GL → Martin
- [x] nginx-Sidecar entfernt (NPM extern)
- [x] Port auf 9982 geändert
- [x] copilot-instructions auf aktuelles Template aktualisiert
- [x] download-data.sh + download-satellite.py erstellt
- [x] History-System (post-commit Hook + _session.md Konvention) in rd13_copilot_setup implementiert
- [x] Docs für MediaWiki, Nextcloud, Home Assistant erstellt
- [x] Planet-MBTiles Download gestartet (OpenFreeMap, 94 GB)
- [x] Martin WebUI aktiviert (`--webui enable-for-all`)
- [x] Endpunkte verifiziert (`/health`, `/catalog`, Root 200)
- [x] MediaWiki-Kartographer Doku in `docs/mediawiki-config.php` erweitert
- [x] MediaWiki-Repo auf Martin umgestellt und committed
- [x] Rate-Limiting-Anforderungen in `docs/requirements/REQUIREMENTS.md` aufgenommen

---

## Offene Aufgaben

- [ ] **Raster-Rendering für Kartographer** (Sprint 2026-06-19)
  - [ ] tileserver-gl in docker-compose.yml
  - [ ] Style osm-intl.json vorbereiten
  - [ ] NPM Routing /osm-intl/{z}/{x}/{y}.png
  - [ ] MediaWiki testen
- [ ] **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