# 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 und weitere Web-Apps.

## Stack
- Language: Shell (Bash/Fish), JSON, Nginx config
- Infrastructure: Docker Compose, TileServer-GL (Node.js), nginx
- Data: MBTiles / PMTiles (OpenMapTiles-Schema), Planetiler (Java)
- Map styles: MapLibre GL / Mapbox GL JSON
- Reverse Proxy: nginx mit CORS + Rate-Limiting

## Architecture
- Pattern: Single-purpose service (tile serving only)
- `tileserver` Container: TileServer-GL rendert Tiles aus MBTiles-Dateien
- `nginx` Container: CORS-Header, Rate-Limiting, Caching-Header, externer Endpunkt
- Kartendaten liegen in `data/` (nicht im Git, da mehrere GB)
- Styles in `data/styles/`, Fonts in `data/fonts/`
- Key constraints:
  - MBTiles/PMTiles nie ins Git committen (.gitignore)
  - Secrets immer via `.env` (`.env` selbst auch ignoriert)
  - CORS muss für alle Dienste im LAN offen sein (internes Netz)

## Conventions
- Branch naming: `feat/<beschreibung>`, `fix/<beschreibung>`
- Commit format: Conventional Commits (`feat|fix|chore|docs|refactor|ci`)
- File structure:
  ```
  config/        TileServer-GL config.json
  data/          MBTiles, Fonts, Sprites, Styles (nicht im Git)
  docs/          Integrations-Anleitungen (MediaWiki, Nextcloud, API)
  nginx/         nginx.conf, cors.conf
  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 tileserver` – 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:PORT/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
- Styles müssen auf `http://localhost:8080` zeigen (intern) – nginx setzt öffentliche URL
- 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: `/styles/{name}.json` und `/data/{name}.json`

## Security
- Keine Secrets in config.json oder nginx.conf
- nginx Rate-Limiting aktiv halten (100r/s, Burst 200)
- Ports: nginx nach außen, tileserver nur intern (expose, nicht ports)
- 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