tileserver-gl

TileServer GL

Vector and raster maps with GL styles. Server-side rendering by MapLibre GL Native. Map tile server for MapLibre GL JS, Android, iOS, Leaflet, OpenLayers, GIS via WMTS, etc.

Download vector tiles from OpenMapTiles.

Getting Started with Node

Make sure you have Node.js version 20 or above installed. Node 24 is recommended. (running node -v it should output something like v24.x.x). Running without docker requires Native dependencies to be installed first.

Install tileserver-gl with server-side raster rendering of vector tiles with npm.

npm install -g tileserver-gl

Once installed, you can use it like the following examples.

using a mbtiles file

wget https://github.com/maptiler/tileserver-gl/releases/download/v1.3.0/zurich_switzerland.mbtiles
tileserver-gl --file zurich_switzerland.mbtiles
[in your browser, visit http://[server ip]:8080]

using a config.json + style + mbtiles file

wget https://github.com/maptiler/tileserver-gl/releases/download/v1.3.0/test_data.zip
unzip test_data.zip
tileserver-gl
[in your browser, visit http://[server ip]:8080]

Alternatively, you can use the tileserver-gl-light npm package instead, which is pure javascript, does not have any native dependencies, and can run anywhere, but does not contain rasterization on the server side made with Maplibre GL Native.

Getting Started with Docker

An alternative to npm to start the packed software easier is to install Docker on your computer and then run from the tileserver-gl directory

Example using a mbtiles file

wget https://github.com/maptiler/tileserver-gl/releases/download/v1.3.0/zurich_switzerland.mbtiles
docker run --rm -it -v $(pwd):/data -p 8080:8080 maptiler/tileserver-gl:latest --file zurich_switzerland.mbtiles
[in your browser, visit http://[server ip]:8080]

Example using a config.json + style + mbtiles file

wget https://github.com/maptiler/tileserver-gl/releases/download/v1.3.0/test_data.zip
unzip test_data.zip
docker run --rm -it -v $(pwd):/data -p 8080:8080 maptiler/tileserver-gl:latest
[in your browser, visit http://[server ip]:8080]

Example using a different path

docker run --rm -it -v /your/local/config/path:/data -p 8080:8080 maptiler/tileserver-gl:latest

replace '/your/local/config/path' with the path to your config file

Alternatively, you can use the maptiler/tileserver-gl-light:latest docker image instead, which is pure javascript, does not have any native dependencies, and can run anywhere, but does not contain rasterization on the server side made with Maplibre GL Native.

Getting Started with Linux cli

Test from command line

wget https://github.com/maptiler/tileserver-gl/releases/download/v1.3.0/test_data.zip
unzip -q test_data.zip -d test_data
xvfb-run --server-args="-screen 0 1024x768x24" npm test

Run from command line

xvfb-run --server-args="-screen 0 1024x768x24" node .

Documentation

You can read the full documentation of this project at https://tileserver.readthedocs.io/en/latest/.

Security: Host header poisoning (HNP) mitigation

When the server is started without --public_url, URLs in responses (WMTS, TileJSON, style JSON) are built from the request’s Host and X-Forwarded-* headers. If an attacker can influence these headers, the server may return URLs pointing to an attacker-controlled host (Host header poisoning). Clients that use those URLs can then be directed to malicious servers.

Recommended for production:

• Set a canonical public URL so the server never derives host from the request:

  tileserver-gl --public_url https://your-domain.com/ --file your.mbtiles
  

• Or restrict which hosts are allowed when not using --public_url, via the allowed-hosts list (default is *, i.e. no restriction):

  • Set the environment variable TILESERVER_GL_ALLOWED_HOSTS to a comma-separated list of allowed hostnames (e.g. localhost,myapp.example.com). If the request’s host (or X-Forwarded-Host) is not in this list, the server returns path-only URLs instead of absolute URLs, so responses cannot be poisoned with an attacker’s host.
  • Example:

    export TILESERVER_GL_ALLOWED_HOSTS="localhost,map.example.com"
    tileserver-gl --file your.mbtiles
    

  • If you do not set this variable (or set it to *), behavior is unchanged and all hosts are accepted; for public-facing deployments you should either use --public_url or set TILESERVER_GL_ALLOWED_HOSTS to your known host(s). See SECURITY.md for details.

Alternative

Discover MapTiler Server if you need a map server with easy setup and user-friendly interface.