How does the VersaTiles server work?

The VersaTiles server is built in Rust and provides excellent performance with low resource usage. In this article, we'll look at the main components and functionality of the VersaTiles server.

File Format

One of the core concepts of VersaTiles is the unique .versatiles file format for storing map data. This format not only contains all the map tiles for the entire planet, but also has an index of all the map tiles with their respective byte offset and length within the file.

The .versatiles format does not need to be stored locally. It can be accessed remotely over HTTP using byte range requests, which allow the server to fetch only the specific bytes that contain a requested tile. This means the server can serve tiles directly from a remote file without downloading it first, which makes it straightforward to build scalable map infrastructures backed by cloud storage.

The idea to develop a container that can be accessed via HTTP byte range request is based on COMTiles and PMTiles. However, since we have a slightly different focus and saw the need to deviate from the previous implementations if necessary, we decided to develop our own standard. However, we are very open to supporting COMTiles and PMTiles as alternatives in our pipeline.

Installation and setup

First you need to install VersaTiles. See the instructions in the documentation: Installing VersaTiles.

You will also need our prepared map tiles. You can find more information on this in the instructions: Downloading map tiles.

Usage

You can then start the server by using versatiles with the subcommand serve and then simply adding the versatiles file as argument:

versatiles serve planet.versatiles

Multiple sources

If you want to serve more than one source, you can easily add them:

versatiles serve planet.versatiles satellite_imagery.mbtiles my_overlay.tar

When the server is started, all sources and their URL are listed:

   /tiles/planet/*                 <-  /tiles/planet.versatiles
   /tiles/satellite_imagery/*      <-  /tiles/satellite_imagery.mbtiles
   /tiles/my_overlay/*             <-  /tiles/my_overlay.tar

Each source gets an URL based on the file name (without extension). If you want to use a different URL, you can use this special notation with square brackets:

versatiles serve "[osm]planet.versatiles" "[satellite]satellite_imagery.mbtiles" "[heatmap]my_overlay.tar"

Now the URLs look like this:

   /tiles/osm/*                    <-  /tiles/planet.versatiles
   /tiles/satellite/*              <-  /tiles/satellite_imagery.mbtiles
   /tiles/heatmap/*                <-  /tiles/my_overlay.tar

Optional frontend

You can extend the VersaTiles server with an optional frontend. This frontend includes the latest version of MapLibre GL JS, map styles, fonts and symbols. You can download the frontend:

wget "https://github.com/versatiles-org/versatiles-frontend/releases/latest/download/frontend.br.tar.gz"

You can then add the frontend to the server by adding the tar file with a -s argument:

versatiles serve -s frontend.br.tar.gz planet.versatiles

Different IP/Port

By default versatiles uses 0.0.0.0:8080. If you want to change IP/Port use the options:

• -i/--ip: e.g. -i 127.0.0.1
• -p/--port: e.g. -p 3000

Configuration file

For more complex setups — multiple tile sources, CORS rules, custom domain, logging — the server can be configured via a config.yaml file:

versatiles serve --config config.yaml

See the reference model for the full config.yaml schema.

What's not included?

The VersaTiles server implements only core functionality to keep the project simple and easy to maintain. TLS certificates and caching are not included. You can use a CDN or a reverse proxy such as nginx — see the deployment guides for how to set this up.

Scalability and performance

Rust, the programming language used to develop the VersaTiles server, is known for its performance and low resource consumption. As a result, the VersaTiles server can handle a large number of concurrent requests while maintaining fast response times. This makes it ideal for applications ranging from small projects to large, data-intensive infrastructures.