rd13_tile_server/docs/history/summary/PROJECT_CONTEXT.md

# PROJECT_CONTEXT – rd13_tile_server

**Letzte Aktualisierung:** 2026-07-01 – ✅ **Marker-API**: Go-Service für Maptiler-kompatible Marker-Endpunkte (`/styles/v4/marker/*`) hinzugefügt. Forgejo CI baut + pusht Image in lokale Container-Registry.

---

## Projektziel

Selbst gehosteter Tile Server für MediaWiki (Kartographer), Nextcloud, Home Assistant.
**Stack:** Martin (Vektor-API) + tileserver-gl (Raster PNG) + marker-api (Go) + 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`)
- **Marker-API:** `192.168.178.6:8083/cschulz/rd13_tile_server-marker-api:latest` (Port 9984 → `/styles/v4/marker/*.png`)
- **Style:** OSM Bright GL (128 Layer, Wanderwege, POIs, vollständige Weltkarte)
- **Proxy:** Caddy (`rd13_system_proxy`) – SSL, Routing `/styles/v4/marker/*` → 9984, `/styles/` → 9983, rest → 9982
- **Konfiguration:** `config/tileserver.json`, `config/styles/osm-intl.json`
- **Daten:** `data/osm.mbtiles` (95 GB, Planet z0–14), `data/sprites/`, `data/fonts/`
- **Satellit:** `docker-compose.download.yml` → `data/satellite.mbtiles` (~38 GB, z0–11, noch nicht gestartet)
- **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

### Planetiler Build (Host) – Stand 2026-06-15
- ✅ Build abgeschlossen: `build/output/europe.mbtiles` (~103 GB)
- ✅ Container-Exit: `Exited (0)`
- ✅ Ziel-Zoom: `maxzoom=16` bestaetigt (MBTiles-Metadata)
- ✅ Reuse-Artefakte vorhanden: `build/tmp/reuse/feature.db` + `.strings` + `.manifest`
- ✅ Quelle auf Server kopiert: `data/osm-europe.mbtiles` via `rsync`

### Neue Build-Betriebslogik (SSD-Kontrolle)
- `docker-compose.build.yml` nutzt jetzt getrennte Temp-Pfade:
  - `--tmpdir=/data/tmp/work`
  - `--temp_nodes=/data/tmp/work/node.db`
  - `--temp_multipolygons=/data/tmp/work/multipolygon.db`
  - `--temp_features=/data/tmp/reuse/feature.db`
- Neues Steuer-Skript: `scripts/planetiler-build-control.sh`
  - Modi: `status`, `resume`, `fresh`, `fresh-all`, `clean-work`, `clean-all`
- Admin-Doku aktualisiert: `docs/ADMIN.md` (Abschnitt Build-Steuerung/Cleanup)

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

### Vorhandene Daten in `/data/`
| Datei/Ordner | Größe | Status |
|---|---|---|
| `osm.mbtiles` | 95 GB | ✅ Martin-Source `osm` (z0–14) |
| `osm-europe.mbtiles` | 6.4 GB | ✅ Martin-Source `osm-europe` (z0–16, optional) |
| `satellite.mbtiles` | 20 GB | ✅ Martin-Source `satellite` (z0–11, 5.6M Tiles, alle JPEG) |
| `fonts/` | ~4 GB | ✅ 26 Metropolis/Roboto/Noto/OpenSans/PT-Sans-Varianten |
| `styles/` | ~5 MB | ✅ osm-intl.json, config.json |

### Git-Stand
- Branch: `main`
- Letzter Commit: (vor diesem Cleanup+Konvertierungs-Fix)

---

## Aktueller Zustand (2026-06-15) – 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/satellite/{z}/{x}/{y}` (JPEG) | ✅ 200 | image/jpeg |
| `https://tiles.rd13server.de/health` | ✅ 200 | OK |
| `rd13_tileserver` Container | ✅ healthy | Port 9983 |
| `rd13_martin` Container | ✅ healthy | Port 9982 (3 Sources geladen: osm, osm-europe, satellite) |
| Caddy Proxy (`rd13_system_proxy`) | ✅ aktiv | server: Caddy |

**Martin-Catalog (3 Sources):**
```json
[
  { "id": "osm", "name": "OpenStreetMap", "bounds": [-180, -85.05, 180, 85.05], "maxzoom": 14 },
  { "id": "osm-europe", "name": "Europe High Zoom", "bounds": [-10, 35, 45, 72], "maxzoom": 16 },
  { "id": "satellite", "name": "EOX Satellite Imagery", "bounds": [-180, -85.05, 180, 85.05], "maxzoom": 11 }
]
```

**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

- Nextcloud produktiv setzen via `occ` auf `https://tiles.rd13server.de/styles/europa-detail/{z}/{x}/{y}.png`
- Home Assistant Tile-Layer produktiv auf einen der verifizierten Endpunkte setzen
- Optional: EOX-Download auf 12-wöchentliche Automation prüfen (cron-Job via Swag/Nginx overlay)
- Optional: Höhere Zoom-Level (z13–z18) für lokale Hotspots auf Extra-MBTiles bauen

## Offene Aufgaben

- [ ] End-to-End Test gegen `https://tiles.rd13server.de` mit allen 3 Tile-Quellen (osm, osm-europe, satellite)
- [ ] MediaWiki in Browser testen – mapframe/maplink mit Satellit-Daten
- [ ] Optional: Reuse-Workflow beim nächsten Planetiler-Buildlauf validieren (`planetiler-build-control.sh resume`)
- [ ] Optional: EOX-Download auf 12-wöchentliche Automation prüfen

## 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
- EOX liefert einzelne PNG-Tiles trotz `.jpg`-URL → Download-Container konvertiert automatisch

---

## Erledigte Aufgaben

- [x] Git-Repo initialisiert und auf Forgejo gepusht
- [x] Martin WebUI aktiviert (`--webui enable-for-all`)
- [x] Satellit-Download-Container gebaut (resume-fähig, PNG→JPEG on-the-fly)
- [x] 1.505.049 PNG-Tiles zu JPEG konvertiert (22.9 Minuten)
- [x] SQLite-Integritätscheck bestanden (quick_check=ok)
- [x] Martin lädt alle 3 Quellen ohne Fehler
- [x] Temporäre Dateien und Backups gelöscht
- [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