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/*). 32×32px Canvas, schlanker Teardrop-Pin (r/d≈0.35, Öffnungswinkel 20°), 80% Transparenz. 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

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):

[
  { "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

• Git-Repo initialisiert und auf Forgejo gepusht
• Martin WebUI aktiviert (--webui enable-for-all)
• Satellit-Download-Container gebaut (resume-fähig, PNG→JPEG on-the-fly)
• 1.505.049 PNG-Tiles zu JPEG konvertiert (22.9 Minuten)
• SQLite-Integritätscheck bestanden (quick_check=ok)
• Martin lädt alle 3 Quellen ohne Fehler
• Temporäre Dateien und Backups gelöscht
• Endpunkte verifiziert (/health, /catalog, Root 200)
• MediaWiki-Kartographer Doku + LocalSettings konfiguriert
• ADR-001: Martin + tileserver-gl Stack-Entscheidung dokumentiert
• tileserver-gl Service in docker-compose.yml (Port 9983, maptiler/tileserver-gl)
• config/tileserver.json – Service-Konfiguration (MBTiles + Styles + Fonts)
• config/styles/osm-intl.json – MapLibre GL Style für Raster-Rendering
• Caddy-Routing: /styles/osm-intl/* → Port 9983, rest → Port 9982
• 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