Documentation Index
Fetch the complete documentation index at: https://mintlify.com/danizd/urbanviable/llms.txt
Use this file to discover all available pages before exploring further.
TileServer GL (urbanviable-tiles, port 8080) runs in the Docker network urbanviable-net. In the current docker-compose.yml, port 8080 is also published to the host (ports: "8080:8080"), which makes the tile server reachable directly at http://localhost:8080 on the host machine — useful during local development and debugging.
The Nginx reverse proxy (urbanviable-web) fronts tile requests from the browser via the /data/ location:
Client request: GET /data/galicia-scouting/{z}/{x}/{y}.pbf
→ Nginx alias → served from volume /data/ (./tiles_data mounted read-only)
The current Nginx configuration does not include a proxy_pass to urbanviable-tiles. Tile requests served through Nginx use the location /data/ block, which serves static files from the ./tiles_data volume mount. Direct access to TileServer GL metadata and the health endpoint requires either the published host port (localhost:8080) or an internal Docker network request.
TileServer GL Configuration
The tiles_data/config.json file tells TileServer GL where to find the MBTiles file and under what name to register the tileset:
{
"options": {
"paths": {
"root": "/data",
"mbtiles": "/data"
}
},
"data": {
"galicia-scouting": {
"mbtiles": "galicia_scouting.mbtiles"
}
}
}
galicia_scouting.mbtiles file is mounted into the urbanviable-tiles container at /data via the ./tiles_data Docker volume. TileServer GL picks up a replaced .mbtiles file without a container restart — copy the new file into ./tiles_data/ and TileServer GL will serve it on the next tile request.
GET /data/galicia-scouting/{z}/{x}/{y}.pbf
Returns a single vector tile in Mapbox Vector Tile (MVT / PBF) format for the specified tile coordinate.
Path Parameters
| Parameter | Type | Description |
|---|
z | integer | Zoom level. Valid range: 6–14. |
x | integer | Tile column (west-to-east), per the XYZ tile scheme. |
y | integer | Tile row (north-to-south). |
Response
| Property | Value |
|---|
| Content-Type | application/x-protobuf |
| Encoding | Binary (gzip-compressed PBF) |
| Cache-Control | public, max-age=86400 (set by Nginx — 24 hours) |
Layer Inside the Tile
Each .pbf tile contains a single vector layer:
| Property | Value |
|---|
| Layer name | secciones |
| Geometry type | Polygon |
| Feature properties | All 11 columns from the tile schema |
secciones must match the source-layer value in the MapLibre source definition in MapViewer.jsx. A mismatch produces a blank map with no console error.
Feature Properties per Tile
Each polygon feature in the secciones layer carries the full 11-column property set:
cusec, renta_norm, renta_abs, densidad_norm, jovenes_norm, mayores_norm,
poblacion_abs, actividad_norm, actividad_abs, uso_comercial_norm, antiguedad_norm
Example Request
curl -o tile.pbf \
"https://urbanviable.example.com/data/galicia-scouting/8/62/99.pbf"
tippecanoe’s companion tool:
tile-join --no-tile-compression -e ./output_dir galicia_scouting.mbtiles
# Then inspect any .pbf file in output_dir with vt-pbf or similar
Zoom levels outside the range 6–14 are not present in the MBTiles file. Requesting z=5 or z=15 will return a 404 from TileServer GL. MapLibre GL JS handles this automatically: when the map is zoomed in beyond maxzoom: 14, it applies overzoom rendering — it fetches the z=14 tile and renders it at the requested zoom. No additional configuration is required. The minZoom: 6 setting in MapViewer.jsx prevents the user from zooming out further than the available tile coverage.
GET /data/galicia-scouting.json (direct)
Returns tileset metadata as JSON. Use this endpoint to verify that TileServer GL is running and serving the correct tileset, and to confirm the layer name and zoom range.
Response
| Property | Value |
|---|
| Content-Type | application/json |
| Cache-Control | public, max-age=3600 (1 hour) |
Response Fields
| Field | Type | Description |
|---|
name | string | Human-readable tileset name |
format | string | Always "pbf" for vector tilesets |
minzoom | integer | Minimum available zoom level |
maxzoom | integer | Maximum available zoom level |
bounds | array | [west, south, east, north] in WGS84 degrees |
center | array | [longitude, latitude, zoom] — suggested initial view |
vector_layers | array | One object per layer, containing id and fields |
Example Response
{
"name": "galicia-scouting",
"format": "pbf",
"minzoom": 6,
"maxzoom": 14,
"bounds": [-9.301, 41.826, -6.717, 43.790],
"center": [-7.800, 42.800, 7],
"vector_layers": [
{
"id": "secciones",
"fields": {
"cusec": "String",
"renta_norm": "Number",
"renta_abs": "Number",
"densidad_norm": "Number",
"jovenes_norm": "Number",
"mayores_norm": "Number",
"poblacion_abs": "Number",
"actividad_norm": "Number",
"actividad_abs": "Number",
"uso_comercial_norm": "Number",
"antiguedad_norm": "Number"
}
}
]
}
Example Request
curl "http://localhost:8080/data/galicia-scouting.json" | jq .
curl "http://localhost:8080/data/galicia-scouting.json" | jq .vector_layers[0].id
# Expected output: "secciones"
Health Check
TileServer GL exposes an internal health endpoint used by Docker’s healthcheck directive:
| Property | Value |
|---|
| Endpoint | GET http://urbanviable-tiles:8080/health |
| Check interval | Every 30 seconds |
| Exposed externally | Via host port 8080 (published in docker-compose.yml) |
urbanviable-tiles container is healthy before marking dependent services as ready.
External monitoring can use http://localhost:8080/health on the host, or the metadata endpoint http://localhost:8080/data/galicia-scouting.json to exercise the full TileServer GL serving path.