example.toml

# Tileserver-RS Configuration Example
# Copy this file to config.toml and customize for your setup

# ============================================================================
# ROOT-LEVEL CONFIGURATION
# These must come BEFORE any [section] headers due to TOML parsing rules
# ============================================================================

# Path to fonts directory (for serving PBF glyph files)
# The directory structure should be:
#   fonts/
#   ├── Noto Sans Regular/
#   │   ├── 0-255.pbf
#   │   ├── 256-511.pbf
#   │   └── ...
#   └── Open Sans Bold/
#       └── ...
# fonts = "/data/fonts"

# Path to static files directory (for /files/{filename} endpoint)
# Serves arbitrary static files like GeoJSON overlays, custom icons, etc.
# files = "/data/files"

# ============================================================================
# SERVER CONFIGURATION
# ============================================================================
[server]
# Host to bind to (use 0.0.0.0 to listen on all interfaces)
host = "0.0.0.0"
# Port to listen on
port = 8080
# Allowed CORS origins (use ["*"] for all origins)
cors_origins = ["*"]
# Admin server bind address for hot-reload endpoint (default: disabled)
# Set to a loopback address to enable: POST /__admin/reload
# admin_bind = "127.0.0.1:9099"
# Public URL for tile URLs in TileJSON responses (optional)
# Use this when running behind a reverse proxy or Docker with port mapping
# Example: If Docker maps 4000:8080, set public_url = "http://localhost:4000"
# If not set, auto-generated from host:port
# public_url = "http://localhost:4000"

# ============================================================================
# OPENTELEMETRY + PROMETHEUS METRICS
# OTLP push pipeline (traces + metrics) and Prometheus pull-based /metrics
# scrape endpoint. Both pipelines are independent — you can run one without
# the other. See: https://docs.tileserver.app/guides/telemetry
# ============================================================================
[telemetry]
# Enable OTLP tracing + metrics push (default: false)
enabled = false
# OTLP gRPC endpoint (only used when enabled = true)
endpoint = "http://localhost:4317"
# Service name attached to traces and metrics
service_name = "tileserver-rs"
# Trace sampling rate (0.0 = none, 1.0 = all). Metrics ignore this — they
# always export at full fidelity at the configured interval.
sample_rate = 1.0
# Enable OTLP metrics push (default: true; requires enabled = true)
metrics_enabled = true
# OTLP metrics push interval in seconds (default: 60)
metrics_export_interval_secs = 60

# --- Prometheus pull-based scrape endpoint ---
# Spawns a separate HTTP listener for Prometheus to scrape directly. Runs
# independently of `enabled`/`metrics_enabled` above. When `prometheus_bind`
# is unset (the default) the listener task is never spawned and there is
# zero runtime cost — same instruments feed both pipelines via no-op meters.
#
# Bind address for the standalone /metrics listener (default: disabled)
# prometheus_bind = "127.0.0.1:9100"
# HTTP path for the exposition endpoint (default: "/metrics")
# prometheus_path = "/metrics"
# Cardinality strategy for emitted labels:
#   "strict"  (default) — zoom collapsed to low|mid|high buckets; tile
#                         coordinates dropped. Bounded combinations safe
#                         for long-term Prometheus retention.
#   "verbose"           — pass-through (raw zoom 0..=22). Useful for
#                         short-window debugging; can blow up cardinality
#                         if left enabled in production.
# metrics_label_cardinality = "strict"

# ============================================================================
# NATIVE RENDERER POOL (for server-side raster tile generation)
# ============================================================================
[render]
# Number of concurrent renderer worker threads (default: 4)
# Each worker maintains persistent MapLibre Native instances with EGL contexts
pool_size = 4
# Render timeout in seconds — requests exceeding this are dropped (default: 30)
render_timeout_secs = 30

# ============================================================================
# GLOBAL TILE CACHE
# In-process byte-weighted cache shared by all non-PostgreSQL sources.
# PostgreSQL sources have their own [postgres.cache] section.
# ============================================================================
[cache]
enabled = false
max_size_mb = 512
ttl_seconds = 3600
# Scratch / cache directory. Overridden by --cache-dir / TILESERVER_CACHE_DIR.
# Defaults to <system temp dir>/tileserver-rs when unset.
# dir = "/var/cache/tileserver-rs"

# ============================================================================
# TILE SOURCES
# PMTiles and MBTiles files - add multiple sources, each with a unique ID
# ============================================================================

# Example: Local PMTiles file
# [[sources]]
# id = "osm"
# type = "pmtiles"
# path = "/data/osm.pmtiles"
# name = "OpenStreetMap"
# attribution = "<a href=\"https://www.openstreetmap.org/copyright\">© OpenStreetMap</a>"

# Example: Remote PMTiles file (HTTP/HTTPS)
# [[sources]]
# id = "protomaps"
# type = "pmtiles"
# path = "https://build.protomaps.com/20260407.pmtiles"
# name = "Protomaps Tiles"

# Example: S3 PMTiles file
# [[sources]]
# id = "s3-tiles"
# type = "pmtiles"
# path = "s3://my-bucket/tiles.pmtiles"
# name = "S3 Tiles"
# [sources.options]
# aws_region = "us-east-1"
# # Credentials auto-detected from env (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
# # or IAM role. For explicit credentials:
# # aws_access_key_id = "AKIA..."
# # aws_secret_access_key = "..."

# Example: Azure Blob Storage PMTiles file
# [[sources]]
# id = "azure-tiles"
# type = "pmtiles"
# path = "az://tiles-container/world.pmtiles"
# name = "Azure Tiles"
# [sources.options]
# azure_storage_account_name = "mystorageaccount"
# # azure_storage_access_key = "..." or use managed identity

# Example: Google Cloud Storage PMTiles file
# [[sources]]
# id = "gcs-tiles"
# type = "pmtiles"
# path = "gs://my-bucket/tiles.pmtiles"
# name = "GCS Tiles"
# # Credentials auto-detected from GOOGLE_APPLICATION_CREDENTIALS or ADC

# Example: S3-compatible (MinIO, Cloudflare R2, Ceph)
# [[sources]]
# id = "r2-tiles"
# type = "pmtiles"
# path = "s3://tiles-bucket/world.pmtiles"
# name = "R2 Tiles"
# [sources.options]
# aws_endpoint = "https://ACCOUNT_ID.r2.cloudflarestorage.com"
# aws_access_key_id = "..."
# aws_secret_access_key = "..."
# aws_virtual_hosted_style_request = "false"
# aws_allow_http = "false"

# Example: Local MBTiles file
# [[sources]]
# id = "terrain"
# type = "mbtiles"
# path = "/data/terrain.mbtiles"
# name = "Terrain RGB"

# ============================================================================
# MLT (MapLibre Tiles) TRANSCODING (requires --features mlt)
# Serve existing MVT tiles as MLT, or vice versa, via on-the-fly transcoding
# ============================================================================

# Example: Serve MVT source as MLT tiles (MVT→MLT transcoding)
# Clients requesting /data/osm-mlt/{z}/{x}/{y}.mlt get transcoded tiles.
# [[sources]]
# id = "osm-mlt"
# type = "pmtiles"
# path = "/data/osm.pmtiles"
# name = "OpenStreetMap (MLT)"
# serve_as = "mlt"  # Transcode MVT→MLT on the fly

# Example: MLT source (auto-detected from tile data)
# PMTiles with TileType::Unknown are probed — if the first tile matches the
# MLT binary signature (7-bit varint + tag 0x01), format is set to MLT.
# [[sources]]
# id = "vector-mlt"
# type = "pmtiles"
# path = "/data/vector.mlt.pmtiles"
# name = "Vector Tiles (MLT native)"

# Example: MBTiles with MLT format
# Set format = "mlt" or "application/vnd.maplibre-vector-tile" in MBTiles metadata.
# [[sources]]
# id = "mbtiles-mlt"
# type = "mbtiles"
# path = "/data/tiles.mlt.mbtiles"
# name = "MBTiles MLT Source"

# ============================================================================
# RASTER SOURCES (requires --features raster and GDAL system library)
# Supports COG (Cloud Optimized GeoTIFF) and VRT (Virtual Raster) files
# ============================================================================

# Example: Cloud Optimized GeoTIFF with continuous colormap (elevation gradient)
# [[sources]]
# id = "elevation"
# type = "cog"
# path = "/data/dem.tif"
# name = "Digital Elevation Model"
# attribution = "© USGS"
# resampling = "cubic"
# [sources.colormap]
# map_type = "continuous"
# nodata_color = "#00000000"
# entries = [
#   { value = 0.0, color = "#0000ff" },
#   { value = 500.0, color = "#00ff00" },
#   { value = 1000.0, color = "#ffff00" },
#   { value = 2000.0, color = "#ff0000" },
#   { value = 4000.0, color = "#ffffff" },
# ]

# Example: Land cover with discrete colormap (categorical data)
# [[sources]]
# id = "landcover"
# type = "cog"
# path = "/data/nlcd.tif"
# name = "Land Cover Classification"
# resampling = "nearest"
# [sources.colormap]
# map_type = "discrete"
# nodata_color = "#00000000"
# entries = [
#   { value = 11.0, color = "#466b9f" },
#   { value = 21.0, color = "#d99282" },
#   { value = 22.0, color = "#eb0000" },
#   { value = 23.0, color = "#ab0000" },
#   { value = 41.0, color = "#68ab5f" },
#   { value = 42.0, color = "#1c5f2c" },
#   { value = 43.0, color = "#b5c58f" },
#   { value = 52.0, color = "#ccb879" },
#   { value = 71.0, color = "#dfdfc2" },
#   { value = 81.0, color = "#dcd939" },
#   { value = 82.0, color = "#ab6c28" },
#   { value = 90.0, color = "#b8d9eb" },
#   { value = 95.0, color = "#6c9fb8" },
# ]

# Example: VRT (Virtual Raster) for mosaics
# [[sources]]
# id = "imagery"
# type = "vrt"
# path = "/data/mosaic.vrt"
# name = "Satellite Imagery"
# resampling = "lanczos"

# Query parameter override:
# Tiles served from raster sources support ?resampling=<method> to override default
# Example: /data/elevation/14/8192/5461.png?resampling=nearest

# ============================================================================
# STAC SOURCES (requires --features stac, which implies raster/GDAL)
# Discover COG assets from STAC API catalogs at startup
# ============================================================================

# [[sources]]
# id = "sentinel2"
# type = "stac"
# path = "https://earth-search.aws.element84.com/v1"
# name = "Sentinel-2 L2A"
# collection = "sentinel-2-l2a"
# asset_role = "visual"       # STAC asset role to match (default: "visual")
# dynamic = false              # false = discover at startup only (default)
# max_items = 100              # max items to discover (default: 100)

# ============================================================================
# GLOBAL RASTER SETTINGS (optional, requires --features raster)
# ============================================================================
# [raster]
# default_resampling = "bilinear"  # Default for all raster sources
# tile_size = 256                  # Tile size in pixels (256 or 512)

# ============================================================================
# POSTGRESQL FUNCTION SOURCES (requires --features postgres)
# ============================================================================
# PostgreSQL function sources allow serving vector tiles directly from
# PostGIS functions, similar to martin's function source feature.
#
# Your function must have one of these signatures:
#
# Simple function (z, x, y):
#   CREATE FUNCTION my_tiles(z integer, x integer, y integer)
#       RETURNS bytea AS $$ ... $$ LANGUAGE plpgsql;
#
# Function with query parameters (z, x, y, query):
#   CREATE FUNCTION my_tiles(z integer, x integer, y integer, query json)
#       RETURNS bytea AS $$ ... $$ LANGUAGE plpgsql;
#
# Example tile function:
#   CREATE OR REPLACE FUNCTION get_building_tiles(z integer, x integer, y integer)
#       RETURNS bytea AS $$
#   DECLARE
#       mvt bytea;
#   BEGIN
#       SELECT INTO mvt ST_AsMVT(tile, 'buildings', 4096, 'geom') FROM (
#           SELECT
#               ST_AsMVTGeom(geom, ST_TileEnvelope(z, x, y), 4096, 64, true) AS geom,
#               name, height
#           FROM buildings
#           WHERE geom && ST_TileEnvelope(z, x, y)
#       ) AS tile WHERE geom IS NOT NULL;
#       RETURN mvt;
#   END
#   $$ LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE;
#
# [postgres]
# # PostgreSQL connection string
# connection_string = "postgresql://user:password@localhost:5432/mydb"
# # Maximum connections in pool (default: 20)
# pool_size = 20
# # Connection pool timeouts (milliseconds)
# pool_wait_timeout_ms = 30000    # Timeout waiting for connection from pool
# pool_create_timeout_ms = 10000  # Timeout creating new connection
# pool_recycle_timeout_ms = 5000  # Timeout recycling connection
# # SSL certificate paths (optional)
# # ssl_cert = "/path/to/client.crt"
# # ssl_key = "/path/to/client.key"
# # ssl_root_cert = "/path/to/ca.crt"
#
# # Tile cache configuration (optional, disabled if omitted)
# # Caches rendered tiles in memory using LRU with byte-size weighting
# [postgres.cache]
# size_mb = 256        # Maximum cache size in megabytes
# ttl_seconds = 3600   # Cache entry time-to-live (1 hour)
#
# # Function sources
# [[postgres.functions]]
# id = "buildings"
# schema = "public"
# function = "get_building_tiles"
# name = "Buildings"
# attribution = "© My Company"
# minzoom = 10
# maxzoom = 18
# bounds = [-122.5, 37.5, -122.0, 38.0]
#
# [[postgres.functions]]
# id = "roads"
# function = "get_road_tiles"  # schema defaults to "public"
# maxzoom = 14
#
# # Table sources (auto-discover geometry columns, generate optimized SQL)
# [[postgres.tables]]
# id = "buildings"
# table = "buildings"
# geometry_column = "geom"   # Optional: auto-detected from geometry_columns
# id_column = "id"           # Optional: feature ID column
# properties = ["name", "height"]  # Optional: auto-detected if omitted
# minzoom = 0
# maxzoom = 18
# extent = 4096    # MVT tile extent (default: 4096)
# buffer = 64      # Tile buffer in pixels (default: 64)

# ============================================================================
# OGC API FEATURES (auto-enabled for postgres table sources)
# ============================================================================
# PostGIS table sources automatically expose OGC API Features endpoints:
#   GET /ogc                              - Landing page
#   GET /ogc/conformance                  - Conformance classes
#   GET /ogc/collections                  - List all table collections
#   GET /ogc/collections/{id}             - Single collection metadata
#   GET /ogc/collections/{id}/items       - GeoJSON FeatureCollection (supports bbox, limit, offset)
#   GET /ogc/collections/{id}/items/{fid} - Single GeoJSON Feature
#
# QGIS: Add a WFS/OGC API layer pointing to http://localhost:8080/ogc
# ArcGIS: Add an OGC API Features connection
# No additional configuration needed — enabled when postgres tables are configured.

# ============================================================================
# MAP STYLES
# ============================================================================
# Map styles
# Sprites should be placed alongside style.json:
#   styles/my-style/
#   ├── style.json
#   ├── sprite.json
#   ├── sprite.png
#   ├── sprite@2x.json
#   └── sprite@2x.png
# [[styles]]
# id = "osm-bright"
# path = "/data/styles/osm-bright/style.json"
# name = "OSM Bright"

# ============================================================================
# Named multi-source composites (issue #601)
# ----------------------------------------------------------------------------
# A composite merges the vector tiles of several sources into one endpoint.
# Requests to /data/<id>/{z}/{x}/{y}.pbf fetch each member concurrently and
# merge their layers (colliding layer names append features). /data/<id>.json
# returns a merged TileJSON: vector_layers are unioned (deduped by id) and the
# zoom range is intersected (minzoom = max of members, maxzoom = min).
#
# Ad-hoc composites need no config at all: just join ids with '+', e.g.
#   /data/openmaptiles+terrain/{z}/{x}/{y}.pbf
#
# Named composites give a reusable alias:
# [[composites]]
# id = "world-base"
# sources = ["openmaptiles", "terrain"]