Conrad Schulz
cd73f91021
- docker-compose: ghcr.io/maplibre/martin:v1.10.1, Port 3000 - config/martin.yaml: Auto-Discovery MBTiles/Styles/Sprites/Fonts, CORS built-in - nginx-Container entfernt (NPM uebernimmt Proxy/SSL/Routing) - config/config.json + nginx/ entfernt (TileServer-GL Artefakte) - docs: alle Endpunkt-URLs auf Martin-Format aktualisiert - .github/copilot-instructions.md: Stack auf Martin (Rust) aktualisiert - Vorteile: Hot-Reload, CORS built-in, ~10x weniger RAM
75 lines
3.6 KiB
Markdown
75 lines
3.6 KiB
Markdown
# GitHub Copilot – Project Instructions
|
||
|
||
## Project
|
||
Selbst gehosteter Tile-Server (rd13) – stellt Karten-Tiles (OSM Vektor + Satelliten-Raster)
|
||
für interne Dienste bereit: MediaWiki (Kartographer), Nextcloud Maps, Home Assistant und weitere Web-Apps.
|
||
|
||
## Stack
|
||
- Language: Shell (Bash/Fish), YAML, JSON
|
||
- Infrastructure: Docker Compose, Martin (Rust), Nginx Proxy Manager (System-Proxy)
|
||
- Data: MBTiles / PMTiles (OpenMapTiles-Schema), Planetiler (Java)
|
||
- Map styles: MapLibre GL JSON (client-seitiges Rendering)
|
||
- Reverse Proxy: Nginx Proxy Manager (extern, SSL, Routing) – kein eigener nginx-Container
|
||
|
||
## Architecture
|
||
- Pattern: Single-purpose service (tile serving only)
|
||
- `martin` Container: Rust-basierter Tile-Server, serviert Vektor- und Raster-Tiles aus MBTiles/PMTiles
|
||
- Kein nginx-Sidecar – CORS via Martin built-in, Proxy/SSL via NPM
|
||
- Kartendaten liegen in `data/` (nicht im Git, da mehrere GB)
|
||
- Styles in `data/styles/`, Fonts in `data/fonts/`, Sprites in `data/sprites/`
|
||
- Key constraints:
|
||
- MBTiles/PMTiles nie ins Git committen (.gitignore)
|
||
- Secrets immer via `.env` (`.env` selbst auch ignoriert)
|
||
- CORS via Martin-Config (alle Origins erlaubt für LAN)
|
||
|
||
## Conventions
|
||
- Branch naming: `feat/<beschreibung>`, `fix/<beschreibung>`
|
||
- Commit format: Conventional Commits (`feat|fix|chore|docs|refactor|ci`)
|
||
- File structure:
|
||
```
|
||
config/ Martin-Konfiguration (martin.yaml)
|
||
data/ MBTiles, Fonts, Sprites, Styles (nicht im Git)
|
||
docs/ Integrations-Anleitungen (MediaWiki, Nextcloud, Home Assistant, API)
|
||
prompts/ GitHub Copilot Prompt-Templates
|
||
scripts/ Daten-Download, Deploy-Hilfen
|
||
```
|
||
- Naming: snake_case für Dateien, kebab-case für Docker-Service-Namen
|
||
|
||
## Engineering Process
|
||
|
||
### Before starting any task
|
||
1. `docker compose config` – Syntax validieren
|
||
2. `docker compose logs martin` – laufende Fehler prüfen
|
||
3. Impact analysis – betrifft die Änderung CORS, Caching oder Endpunkt-URLs?
|
||
4. Test strategy – mit curl / Browser gegen lokalen Server testen
|
||
|
||
### Definition of Done (DoD)
|
||
- [ ] `docker compose config` fehlerfrei
|
||
- [ ] Server startet ohne Fehler in den Logs
|
||
- [ ] Tile-Endpunkt antwortet (`curl http://localhost:3000/health`)
|
||
- [ ] CORS-Header korrekt gesetzt (prüfen mit `curl -I -H "Origin: ..."`)
|
||
- [ ] Keine Secrets in docker-compose.yml oder Configs
|
||
- [ ] .gitignore schützt MBTiles und .env
|
||
- [ ] Commit message folgt Conventional Commits
|
||
|
||
## Tile-Server spezifische Hinweise
|
||
- Martin serviert Tiles direkt aus MBTiles/PMTiles – kein server-seitiges Rendering
|
||
- Clients (MediaWiki, Nextcloud, HA) rendern OSM-Vektorkacheln via MapLibre GL im Browser
|
||
- Satellit-Raster-Tiles (PNG) werden direkt aus raster MBTiles durchgereicht
|
||
- Hot-Reload: neue `.mbtiles`-Datei in `data/` ablegen → sofort unter `/catalog` sichtbar
|
||
- Zoom-Level 0–14 reichen für die meisten Anwendungsfälle (Dateigröße vs. Detail)
|
||
- Planetiler benötigt min. 4 GB RAM für Deutschland, 8 GB für Europa
|
||
- Satellitenkacheln: kostenfrei nur bis Zoom 10 (NASA GIBS oder maptiler.com)
|
||
- TileJSON-Endpoints: `/{source_id}` z.B. `/osm`, `/satellite`
|
||
- Katalog aller geladenen Sources: `/catalog`
|
||
|
||
## Security
|
||
- Keine Secrets in martin.yaml oder docker-compose.yml
|
||
- NPM Rate-Limiting aktiv halten
|
||
- Port 3000 nur intern exponieren wenn NPM im selben Docker-Netz läuft
|
||
- CORS auf `*` ist für internes LAN akzeptabel – für public deployment einschränken
|
||
|
||
## Non-Functional Requirements
|
||
- Tile-Response: < 200ms für gecachte Tiles
|
||
- Availability: best-effort (kein HA erforderlich)
|
||
- Daten-Update-Zyklus: OSM monatlich (Planetiler-Re-Run), Satellit nach Bedarf
|