Guides
Zero-Config Auto-Detection
Start serving tiles without a config file by pointing at a directory or file
tileserver-rs can auto-detect tile sources, styles, and fonts from the filesystem. No config.toml required.
Priority Chain
Configuration is resolved in this order (first match wins):
| Priority | Flag | Behavior |
|---|---|---|
| 1 | --config path | Load explicit config file (fail if missing) |
| 2 | Positional PATH | Auto-detect from that path |
| 3 | — | Try config.toml then /etc/tileserver-rs/config.toml |
| 4 | — | Auto-detect from current working directory |
Usage
# Auto-detect from CWD (priority 4)
tileserver-rs
# Auto-detect from a directory (priority 2)
tileserver-rs ./tiles/
# Auto-detect from a single file (priority 2)
tileserver-rs my-tiles.pmtiles
# Explicit config (priority 1)
tileserver-rs --config config.toml
What Gets Detected
When scanning a directory, tileserver-rs discovers:
| Pattern | Result |
|---|---|
*.pmtiles | PMTiles tile source |
*.mbtiles | MBTiles tile source |
*/style.json | Map style (ID from parent directory name) |
*.style.json | Map style (ID from filename prefix) |
fonts/ | Fonts directory for glyph serving |
*.geojson | Registered as static files |
The scanner checks the target directory, its immediate children, and any styles/ subdirectory tree.
ID Conflict Resolution
When multiple files share the same stem, tileserver-rs disambiguates by appending the file type:
tiles.pmtiles → id: "tiles"
tiles.mbtiles → id: "tiles-mbtiles"
Conflicts are logged as warnings at startup.
Startup Output
Auto-detection results are logged at INFO level:
INFO Auto-detected from: /data/tiles
INFO Sources: 2 (openmaptiles, terrain)
INFO Styles: 1 (osm-bright)
INFO Fonts: /data/tiles/fonts
WARN Conflict: Source ID 'tiles' conflicted; using 'tiles-mbtiles' for /data/tiles/tiles.mbtiles
Combining with CLI Flags
Auto-detected configuration can be combined with CLI overrides:
tileserver-rs ./tiles/ --host 0.0.0.0 --port 3000 --ui
The --config flag always takes precedence. If an explicit config is provided alongside a positional path, the positional path is ignored.