rd13_tile_server/docs/MAINTAINER.md

Maintainer-Handbuch – rd13_tile_server

Zielgruppe: Entwickler & Maintainer – Menschen, die den Code verstehen, erweitern oder reviewen. Voraussetzung: Entwicklungserfahrung mit Docker, MapLibre GL Styles, OSM-Daten.

---

Architektur – Martin + tileserver-gl Stack

Internet (HTTPS)
    ↓
NPM Reverse Proxy (tiles.rd13server.de, Rate Limiting)
    ├─ /osm/{z}/{x}/{y}.pbf → Martin (Vektor-Tiles)
    └─ /osm-intl/{z}/{x}/{y}.png → tileserver-gl (Raster-PNG)
         ↓
    tileserver-gl renders Martin Vektor → PNG
         ↓
    Martin reads osm.mbtiles (Vector Tiles)
         ↓
    /data/osm.mbtiles (OpenFreeMap snapshot)

Stack-Komponenten:

Komponente	Input	Output	Verantwortung
Martin	osm.mbtiles	/{layer}/{z}/{x}/{y}.pbf	Vektor-API, Tile-Distribution
tileserver-gl	Martin PBF + osm-intl.json	/{style}/{z}/{x}/{y}.png	Rendering, PNG-Tile-Cache
NPM	HTTP Client Requests	HTTPS Responses	Proxy, SSL, Rate-Limit

Verwandte ADRs:

• ADR-001: Tile Rendering Stack – Martin + tileserver-gl

---

Projektstruktur

rd13_tile_server/
├── config/
│   └── martin.yaml                    ← Martin Server-Konfiguration
├── data/
│   ├── osm.mbtiles                    ← OpenFreeMap Vector-Snapshot (~94 GB)
│   ├── styles/
│   │   └── osm-intl.json              ← MapLibre GL Style für Raster-Rendering
│   ├── fonts/
│   │   ├── Metropolis Black/
│   │   ├── Open Sans Regular/
│   │   └── … (47 weitere Font-Varianten)
│   └── sprites/                       ← Marker/Icons (derzeit leer)
├── docs/
│   ├── adr/
│   │   ├── 000-template.md
│   │   └── 001-martin-tileserver-gl-stack.md
│   ├── history/
│   ├── requirements/
│   │   └── REQUIREMENTS.md
│   ├── USER.md, ADMIN.md, MAINTAINER.md
│   └── … (API-Endpoints, Integration-Guides)
├── docker-compose.yml                 ← Martin + tileserver-gl
└── scripts/
    ├── download-data.sh               ← OSM-MBTiles fetcher
    └── download-satellite.py          ← Satellit-MBTiles fetcher (optional)

---

Style-Customization (osm-intl.json)

Die Kartographer-Karten werden von data/styles/osm-intl.json definiert. Das ist eine Standard MapLibre GL Style (v8-kompatibel).

Tipps zum Ändern

1. Farben anpassen (einfach)

"layers": [
  {
    "id": "water-area",
    "paint": {
      "fill-color": "#b0d4fc"  ← Ändere zu z.B. "#0066cc"
    }
  }
]

2. Layer-Sichtbarkeit nach Zoom-Level (mittelschwer)

{
  "id": "poi-icon",
  "minzoom": 14,        ← POI-Icons nur ab Zoom 14 sichtbar
  "maxzoom": 20        ← Max Zoom-Level
}

3. Label-Schriftart (mittelschwer)

"text-font": ["Open Sans Bold"]  ← Verfügbare Fonts in data/fonts/

Verfügbare Fonts (aus /data/fonts/):

• Metropolis (Black, Bold, Light, Regular, Thin + Italic-Varianten)
• Open Sans (Bold, Regular, Semibold + Italic-Varianten)
• PT Sans (Bold, Caption, Regular, Narrow + Varianten)
• Roboto (Black, Bold, Light, Medium, Regular, Thin + Italic-Varianten)
• Noto Sans (Bold, Italic, Regular)

4. Linien-Dicke nach Zoom-Level (fortgeschritten)

"line-width": [
  "interpolate",     ← Interpolations-Funktion
  ["linear"],        ← Linear interpolieren
  ["zoom"],          ← Input: aktueller Zoom-Level
  6, 0.5,            ← Bei Zoom 6: 0.5px
  20, 6              ← Bei Zoom 20: 6px
]

Style testen (lokal)

# Nach Änderungen an osm-intl.json:
docker compose restart tileserver

# PNG-Tile abrufen
curl -s "http://localhost:9983/osm-intl/10/544/335.png" -o /tmp/test.png
file /tmp/test.png

# In MediaWiki-Kartographer URL testen:
# https://tiles.rd13server.de/osm-intl/{z}/{x}/{y}.png

---

Martin Vector-Source verstehen

Martin liest Vektor-Daten aus osm.mbtiles und serviert sie als PBF (Protocol Buffers).

Available Layers in osm.mbtiles (abhängig von OpenFreeMap-Schema):

Beispiel: http://localhost:9982/catalog zeigt alle Source-Layer.

Typisch enthalten:

• water – Seen, Flüsse
• landuse – Wald, Park, Gras, Acker
• building – Gebäude-Polygone
• road – Straßen (Motorway, Trunk, Primary, Secondary, etc.)
• railway – Eisenbahn-Linien
• place – Orte (City, Town, Village)
• poi – Points of Interest

Layer in osm-intl.json updaten:

"source": "osm",           ← Vector-Tile-Source (Martin)
"source-layer": "water",   ← Welcher OSM-Layer? (prüfe /catalog)

Falls Layer fehlt → http://localhost:9982/catalog prüfen, oder mit layer in osm-intl.json experimential einen neuen hinzufügen.

---

Rendering-Performance tunen

tileserver-gl Cache:

• Disk-Cache: /tmp/pmtiles-cache (wächst mit Nutzung; max ~50 GB bei voller Coverage)
• Memory: ~500 MB standard, skaliert mit Anfrage-Load
• Warm-up: Erste Anfrage zu neuem Tile-Bereich ist langsam (~100–200ms), danach <20ms

Bottleneck identifizieren:

# Logs verfolgen (live)
docker compose logs -f tileserver | grep "render"

# Performance der Martin-API
curl -w "Time: %{time_total}s\n" -s http://localhost:9982/osm/0/0/0 | head

Falls zu langsam:

1. Martin-Worker-Prozesse erhöhen: config/martin.yaml → worker_processes
2. tileserver-gl Memory erhöhen: docker-compose.yml → deploy.resources.limits.memory

---

Tests & Validierung

Tile-Integrität checken

# Vektor-Tile (PBF) abrufen und inspizieren
curl -s "http://localhost:9982/osm/0/0/0.pbf" | file -
# Should: PBF (Tile protocol buffer)

# Raster-Tile (PNG) abrufen und prüfen
curl -s "http://localhost:8080/osm-intl/0/0/0.png" -o /tmp/t.png
file /tmp/t.png
# Should: image/png

# MediaWiki-Test URL
# https://tiles.rd13server.de/osm-intl/0/0/0.png

Smoke-Test nach Update

# Nach Tile-Daten-Update (osm.mbtiles):
for zoom in 0 5 10 14; do
  curl -s "http://localhost:9983/osm-intl/$zoom/0/0.png" \
    -o /tmp/test_z$zoom.png && echo "✓ Zoom $zoom" || echo "✗ Zoom $zoom"
done

---

Deployment & Release

Checklist vor Push

• docker compose logs prüfen – keine Errors
• Test-Tiles (Zoom 0, 5, 10, 14) erfolgreich
• REQUIREMENTS.md aktualisiert (falls Anforderung geändert)
• ADR erstellt (falls architektur-relevant)
• ADMIN.md / MAINTAINER.md aktualisiert
• CHANGELOG.md aktualisiert (falls vorhanden)
• Git commit + push

Version & Releases

Derzeit: rolling release (jeder Commit ist live).

Falls später strikte Versionierung nötig:

• Versioning: Semantic Versioning (MAJOR.MINOR.PATCH)
• Releases: Tag in Git + Changelog
• Example: v1.0.0 (Martin 0.9.0 + tileserver-gl 4.7.0)

---

Bekannte Limitations & Future TODOs

Jetzt (ADR-001):

• ✅ Martin + tileserver-gl für statische 2–4×/Year Updates
• ✅ Styles anpassbar (osm-intl.json)
• ✅ Fonts + Sprites nutzbar

Zukünftig (Falls nötig):

• ADR-002: Live OSM-Update-Pipeline (OpenMapTiles Server)
• Sprites/Icons erweitern (derzeit leer)
• Mehrere Styles pro Kartographie-Kontext (dark mode, print-optimized)
• Horizontal scaling (Kubernetes / Load Balancer)

---

Ressourcen

• Martin Tile Server Documentation
• tileserver-gl Documentation
• MapLibre GL Style Specification v8
• OpenMapTiles Schema
• OSM Wiki: Map Tiles cd

Dependencies installieren

Dev-Server starten

---

## Architekturentscheidungen (ADRs)

ADR-Dateien liegen unter `docs/adr/`. Format: `NNN-titel.md`.

| Nr. | Titel | Status | Datum |
|---|---|---|---|
| 000 | Template | accepted | … |

---

## Coding-Konventionen

<!-- TODO: Projektspezifische Konventionen -->

- **Branches:** `feat/<ticket>-beschreibung`, `fix/<ticket>-beschreibung`
- **Commits:** Conventional Commits (`feat|fix|chore|docs|refactor|test|ci`)
- **Tests:** `tests/` spiegelt Source-Struktur, ≥ 80% Coverage
- **Linting:** …

---

## Agent-Kontext & History

Der Agent liest beim Start immer `history/summary/PROJECT_CONTEXT.md`.
Nach Abschluss einer Aufgabe wird dort der Projektzustand aktualisiert.

- Vollständige Konversationen: `history/prompts/` (committed – History bleibt vollständig erhalten)
- Komprimierter Kontext: `history/summary/PROJECT_CONTEXT.md` (committed)

---

## Neues Feature hinzufügen

1. `history/summary/PROJECT_CONTEXT.md` lesen – aktuellen Stand verstehen
2. Issue / Ticket anlegen
3. Branch: `git checkout -b feat/<ticket>-beschreibung`
4. Implementieren + Tests schreiben
5. Dokumentation in `docs/USER.md` oder `docs/ADMIN.md` aktualisieren
6. `git commit` – Quality Gate läuft automatisch (pre-commit hook)
7. PR erstellen + Review

---

## Designentscheidungen

| Entscheidung | Begründung |
|---|---|
| … | … |