331 lines
8.6 KiB
Markdown
331 lines
8.6 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
# 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)**
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
### Höhere Zoom-Level bauen (auf Host-Rechner, nicht auf dem Server)
|
||
|
||
Planetiler läuft in einem eigenen Container auf dem **Host-Rechner** (MacBook, Desktop-PC
|
||
etc.) mit genug RAM. Das Ergebnis wird per `rsync` auf den Server übertragen.
|
||
|
||
```bash
|
||
# Auf dem HOST-RECHNER ausführen (nicht auf dem Server):
|
||
cd /path/to/rd13_tile_server
|
||
|
||
# Germany z0-16 (~12 GB, ~2h, 8 GB RAM)
|
||
AREA=germany MAX_ZOOM=16 RAM=8g docker compose -f docker-compose.build.yml up
|
||
|
||
# Europe z0-16 (~80 GB, ~12h, 16 GB RAM)
|
||
AREA=europe MAX_ZOOM=16 RAM=16g docker compose -f docker-compose.build.yml up
|
||
|
||
# Fertige Datei auf Server übertragen (resume-fähig via rsync):
|
||
rsync -avh --progress \
|
||
./build/germany.mbtiles \
|
||
rd13server@192.168.178.6:/mnt/services-data/rd13_tile_server/data/osm-germany.mbtiles
|
||
|
||
# Martin auf dem Server neu starten:
|
||
ssh rd13server@192.168.178.6 \
|
||
"cd /mnt/services-data/rd13_tile_server && docker compose restart martin"
|
||
|
||
# Neue Source prüfen:
|
||
curl https://tiles.rd13server.de/catalog | python3 -m json.tool | grep osm-germany
|
||
```
|
||
|
||
Output liegt lokal unter `./build/<AREA>.mbtiles` (gitignored).
|
||
|
||
### 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`.
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
# 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:**
|
||
```nginx
|
||
# 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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:**
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
<!-- TODO: Alle relevanten Env-Vars dokumentieren -->
|
||
|
||
| Variable | Pflicht | Default | Beschreibung |
|
||
|---|---|---|---|
|
||
| `EXAMPLE_VAR` | ✓ | – | Beschreibung |
|
||
|
||
### Persistente Daten (`/data/`)
|
||
|
||
Alle persistenten Daten liegen unter `/data/<service>/` im Repo-Root:
|
||
|
||
<!-- TODO: Alle Service-Unterordner und was drin liegt -->
|
||
|
||
| 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
|
||
|
||
<!-- TODO: Wie überwacht man das System? Wo sind die Logs? -->
|
||
|
||
```bash
|
||
# Logs ansehen
|
||
docker compose logs -f <service>
|
||
|
||
# Status prüfen
|
||
docker compose ps
|
||
```
|
||
|
||
---
|
||
|
||
## Sicherheit
|
||
|
||
<!-- TODO: Firewall-Regeln, Portfreigaben, TLS-Setup etc. -->
|
||
|
||
- Offene Ports: …
|
||
- TLS: …
|
||
- Zugriffskontrolle: …
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
| Symptom | Ursache | Lösung |
|
||
|---|---|---|
|
||
| … | … | … |
|
||
|
||
---
|
||
|
||
## Disaster Recovery
|
||
|
||
<!-- TODO: Was tun wenn es brennt? -->
|
||
|
||
1. Dienst stoppen: `docker compose down`
|
||
2. Backup einspielen: …
|
||
3. Dienst neu starten: `docker compose up -d`
|