cschulz/rd13_tile_server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
rd13_tile_server/docs/ADMIN.md

7.5 KiB
Raw Blame History

Administrator-Handbuch – rd13_tile_server

Zielgruppe: Administratoren – Menschen, die das System betreiben, deployen und konfigurieren. Voraussetzung: Grundkenntnisse in Linux, Docker und der eingesetzten Stack (Martin, tileserver-gl).

Systemvoraussetzungen

Komponente Mindestanforderung Empfohlen
OS Linux 5.10+ (oder macOS 12+) Ubuntu 22.04 LTS
RAM 1 GB 2-4 GB
Disk 5 GB (OS + Containers) 20 GB (mit Cache-Warmup)
Dependencies Docker 20.10+, docker-compose 2.0+ Docker Desktop / Compose v2
Network Port 9982 (Martin), Port 8080 (tileserver-gl) internal Public domain via NPM reverse proxy

Deployment

Erstes Aufsetzen

# Repository klonen
git clone ssh://git@192.168.178.6:2222/cschulz/rd13_tile_server.git /mnt/services-data/rd13_tile_server
cd /mnt/services-data/rd13_tile_server

# Daten-Verzeichnis initialisieren (falls nicht vorhanden)
mkdir -p data/{fonts,sprites,styles}

# Services starten
docker compose up -d

# Health-Checks verifizieren
docker compose ps
curl -s http://localhost:9982/health | jq .
curl -s http://localhost:8080/health

Updates einspielen (Tile-Daten)

Szenario: osm.mbtiles aktualisieren (2–4×/Jahr)

# 1. Neue MBTiles herunterladen (z.B. von OpenFreeMap)
cd /mnt/services-data/rd13_tile_server
python3 scripts/download-data.sh data/osm.mbtiles.new

# 2. Alte Datei backup-en
mv data/osm.mbtiles data/osm.mbtiles.$(date +%Y%m%d)

# 3. Neue Datei aktivieren
mv data/osm.mbtiles.new data/osm.mbtiles

# 4. Container neu starten (warm caches)
docker compose restart martin tileserver

# 5. Health-Check + Sampling testen
curl -s http://localhost:9982/osm | jq .
curl -s "http://localhost:9983/osm-intl/0/0/0.png" > /tmp/test.png && file /tmp/test.png

Satellit-Tiles herunterladen (einmalig, ~38 GB, ~24h)

Der Download läuft in einem eigenen Container – vollständig unabhängig von SSH-Sessions und VS Code. Resume-fähig: bei Unterbrechung einfach neu starten.

Ressourcen: 16 Threads, 2 GB RAM-Limit, 4 CPUs – konfigurierbar in docker-compose.download.yml.

cd /mnt/services-data/rd13_tile_server

# Starten (läuft im Vordergrund, Logs direkt sichtbar)
docker compose -f docker-compose.download.yml up

# Status in zweitem Terminal verfolgen
docker compose -f docker-compose.download.yml logs -f

# Pausieren
docker compose -f docker-compose.download.yml stop

# Fortsetzen (bereits heruntergeladene Tiles werden übersprungen)
docker compose -f docker-compose.download.yml up

Wenn fertig: data/satellite.mbtiles (~38 GB) liegt bereit. Martin lädt sie automatisch beim nächsten Restart als Source satellite.

Service Restart / Update Images

# Nur Image-Updates (Martin, tileserver-gl)
docker compose pull
docker compose up -d

# Bei Compose-Konfiguration-Änderungen
docker compose down
docker compose up -d

# Logs ansehen
docker compose logs -f martin     # Martin Vektor-API
docker compose logs -f tileserver # Raster-Rendering

Konfiguration

Tile-Server-Komponenten

Martin (Vektor-Tiles)

  • Konfiguration: config/martin.yaml
  • API Root: http://localhost:9982
  • Catalog: http://localhost:9982/catalog
  • Datenquelle: data/osm.mbtiles

tileserver-gl (Raster-PNG-Rendering)

  • Konfiguration: Styles unter data/styles/
  • API Root: http://localhost:9983 (exposed port)
  • Style osm-intl: data/styles/osm-intl.json
  • Fonts: data/fonts/
  • Sprites: data/sprites/

Reverse Proxy (NPM) – Öffentliche URLs

Konfiguration (manuell im NPM WebUI):

  1. Neuer Proxy-Host: tiles.rd13server.de

    • Forward Hostname/IP: martin (Docker-DNS)
    • Forward Port: 3000
    • Schema: http
    • Websockets Support: ☑

  2. Advanced Tab – Custom Nginx Config:

    # Rate Limiting
limit_req_zone $binary_remote_addr zone=tiles:10m rate=10r/s;
limit_conn_zone $binary_remote_addr zone=tile_conn:10m;

location / {
    limit_req zone=tiles burst=60 nodelay;
    limit_conn tile_conn 20;
    limit_req_status 429;
    limit_conn_status 429;

    # Cache-Header für Tiles
    add_header Cache-Control "public, max-age=86400, stale-while-revalidate=3600" always;
    add_header Vary "Accept-Encoding" always;
}

# Raster-Routing zu tileserver-gl
location ~ ^/osm-intl/ {
    proxy_pass http://localhost:9983;
    proxy_ssl_server_name on;
    add_header Cache-Control "public, max-age=86400" always;
}

Betrieb & Monitoring

Health-Checks manuell

# Martin Vektor-Tiles
curl -s http://localhost:9982/health

# tileserver-gl Raster
curl -s http://localhost:9983/health

# Sample-Tile abrufen (PNG)
curl -s "http://localhost:9983/osm-intl/0/0/0.png" -o /tmp/tile.png
file /tmp/tile.png

Performance-Baseline

Erwartete Antwortzeiten (ohne externen Upstream):

  • Martin /osm/{z}/{x}/{y}.pbf: <50ms (cache warm)
  • tileserver-gl /osm-intl/{z}/{x}/{y}.png: <100ms (cache cold), <20ms (cache warm)

Caches (auto-warm nach Start):

  • Martin: in-memory (fast)
  • tileserver-gl: Disk unter /tmp/pmtiles-cache (wächst mit Nutzung)

Logs

# Alle Services
docker compose logs

# Nur Fehler
docker compose logs --tail=100 | grep -i error

# Real-time verfolgen
docker compose logs -f

Troubleshooting

Problem Ursache Lösung
tiles.rd13server.de liefert 502 Martin-Container nicht erreichbar docker compose ps + docker compose logs martin
PNG-Tiles sind grau/leer tileserver-gl kann Martin nicht erreichen Docker-Network prüfen: docker network inspect rd13_tile_server_default
Lange Antwortzeiten Tile-Cache kalt, erste Render Normal; nach 10–20 Requests warm; monitoring via logs
Out of Memory Cache wächst unbegrenzt tileserver-gl Speicher-Limit setzen oder Cache-TTL anpassen

Wartungsplan

Task Frequenz Aufwand
Tile-Daten aktualisieren 2–4×/Jahr 15 min (Script + Restart)
Container-Images patchen Wöchentlich 5 min (docker compose pull && up -d)
Logs archivieren Monatlich 5 min (via logrotate)
Disk-Space überwachen Wöchentlich 2 min (du/df)

Rollback-Procedure

Falls neue osm.mbtiles kaputt ist:

cd /mnt/services-data/rd13_tile_server
docker compose stop martin tileserver

# Alte Version zurückbringen
rm data/osm.mbtiles
mv data/osm.mbtiles.YYYYMMDD data/osm.mbtiles

docker compose up -d
Variable Pflicht Default Beschreibung
EXAMPLE_VAR ✓ – Beschreibung

Persistente Daten (/data/)

Alle persistenten Daten liegen unter /data/<service>/ im Repo-Root:

Pfad Inhalt Backup-Priorität
data/<service>/ … hoch/mittel/niedrig

Backup-Hinweise:

  • /data/ komplett sichern vor jedem Update
  • Empfehlung: tägliches Backup via Cron / Restic / rsync

Monitoring & Logs

# Logs ansehen
docker compose logs -f <service>

# Status prüfen
docker compose ps

Sicherheit

  • Offene Ports: …
  • TLS: …
  • Zugriffskontrolle: …

Troubleshooting

Symptom Ursache Lösung
… … …

Disaster Recovery

  1. Dienst stoppen: docker compose down
  2. Backup einspielen: …
  3. Dienst neu starten: docker compose up -d