stsdockerhub/tileserver-gl repository overview

⁠TileServer GL — self-hosted OpenStreetMap tiles

Vector and raster map tile server with GL styles, built from a vendored and extended fork of maptiler/tileserver-gl⁠ (v5.7.0-pre.0). Serves OpenMapTiles⁠-schema MBTiles/PMTiles, for example generated from OpenStreetMap / Geofabrik extracts with Planetiler⁠, to MapLibre GL JS, Android/iOS, Leaflet, OpenLayers and GIS clients via WMTS.

Source, docs and dev stack: https://github.com/tgivslife/openstreetmap-tileserver-gl⁠

⁠Image variants

All variants live in this repository; the tag suffix selects the build.

Current version: 5.7.0-pre.0 → 5.7.0-pre.0, 5.7.0-pre.0-light, 5.7.0-pre.0-light-s3.

⁠What's added on top of upstream

• S3 / object storage data sources. PMTiles from s3:// (AWS), s3+https:// / s3+http:// (MinIO, Ceph, R2, …) or plain https:// range reads. Private buckets use the standard AWS credential chain (env vars, mounted ~/.aws profile, IAM role); credentials are never read from config.json.
• ${VAR} / ${VAR:-default} substitution in any config.json string, so one baked config works across deployments.
• API keys and expiring HMAC tokens (?key=), propagated automatically into every generated URL, plus an optional Origin/Referer allowlist for hotlink deterrence.
• CDN-friendly Cache-Control on every successful response (configurable per category).
• Prometheus metrics on a separate loopback-bound port.
• /health endpoint used by the built-in Docker HEALTHCHECK; stays open when auth is enabled.
• Config reload on SIGHUP without restarting the container.
• Light/dark theme toggle in the style viewer for any style that has a -dark sibling.

⁠Quick start

⁠Serve a local MBTiles file (light image)

# Generate tiles first, e.g. with Planetiler:
docker run -e JAVA_TOOL_OPTIONS="-Xmx1g" -v "$(pwd)/data":/data \
  ghcr.io/onthegomap/planetiler:latest --download --area=monaco

docker run --rm -it -v "$(pwd)/data":/data -p 8080:8080 \
  stsdockerhub/tileserver-gl:5.7.0-pre.0-light

Open http://localhost:8080/⁠. With no config.json in /data, the server picks up the first *.mbtiles / *.pmtiles file it finds and, for OpenMapTiles-format data, serves the bundled styles against it.

⁠Server-side rendering (full image)

docker run --rm -it -v "$(pwd)/data":/data -p 8080:8080 \
  stsdockerhub/tileserver-gl:5.7.0-pre.0

⁠Stateless S3 deployment

docker run --rm -it -p 8080:8080 \
  -e PMTILES_URL="s3+https://minio.example.com/tiles/planet.pmtiles" \
  -e AWS_ACCESS_KEY_ID=... \
  -e AWS_SECRET_ACCESS_KEY=... \
  stsdockerhub/tileserver-gl:5.7.0-pre.0-light-s3

A complete MinIO example (private bucket, SigV4) is in tileserver-gl-dev/compose.s3.yml⁠.

⁠Bundled styles (-light-s3)

osm-openmaptiles, streets-v2, basic-v2, each with a -dark variant and its own sprite sheet, localized to be served entirely by this server (no external API key). Includes 28 glyph sets (Noto Sans, Open Sans and variants).

⁠Environment variables

All optional.

Full descriptions: USAGE.md › Environment variables⁠.

⁠Ports and endpoints

Key endpoints: /styles/{id}/style.json, /data/{id}/{z}/{x}/{y}.pbf, /fonts/{fontstack}/{range}.pbf, /styles/{id}/ (viewer). Full image only: /styles/{id}/{z}/{x}/{y}.png, /styles/{id}/static/…, /data/{id}/elevation/…, /styles/{id}/wmts.xml.

⁠Performance

Light image reading from MinIO over S3 (Romania tileset, z8–14, k6, 0 errors):

Containers are stateless. Scale out horizontally and put a CDN in front; the cache headers are already set for it.

⁠Operations

docker kill -s HUP <container>   # reload config.json without a restart

⁠Documentation

Install⁠ · Usage & endpoints⁠ · Configuration⁠ · Deployment⁠

⁠Credits

Based on TileServer GL⁠ by MapTiler and the OpenMapTiles⁠ schema. Map data © OpenStreetMap⁠ contributors (ODbL). Styles derived from MapTiler / OpenMapTiles styles. Keep the required attributions visible on any map you publish.