Why Would I Want to Use Docker to Serve Local Mapbox Vector Tiles?

• You really want a custom vector tile basemap but it needs to be totally offline
• You’d like to use your own server rather than Mapbox (and you’re willing to put in the extra work)
• You’d like to use a custom basemap in a desktop GIS

Background

A year or so ago Laurence Liss wrote an excellent Azavea blog about how to serve Mapbox Studio Classic vector tiles for an offline mobile app. His detailed post included every step along the way, including how he solved a number of hiccups, and he closed with a custom Ansible Role and Vagrant file to package it all up more easily.

Trying Vagrant and Ansible

I set out to use his Vagrant configuration to run my own virtual machine to serve vector tiles, but things weren’t so straightforward. Many of the software libraries used in the Vagrant file have been updated since the blog was published, introducing many difficult conflicts. After much fruitless conflict resolution, I stumbled upon a solution: Docker. Docker is a technology that uses ‘images’ to share and run pre-configured virtual machines as development environments or applications.

Enter Docker

It turns out that another company, Klokan Technologies (creators of MapTiler and partly responsible for OSM2VectorTiles.org), put together a Docker image that contains many of the same programs Laurence installed using Vagrant. Docker images are guaranteed to work on any computer that can run Docker because they’re exact copies of a virtual machine. It’s worth running through the Docker tutorial to learn more about how the technology works (and also because I probably didn’t do it justice).

Ingredients:

Note: These directions assume OSX. Windows users may find behavior and steps are slightly different.

• Docker installed with its included Kitematic interface
• Mapbox Studio Classic
• An MBTILES file to display. Where does one find an MBTiles file?
  • Export from a Mapbox Studio Classic source
  • Download from OSM2VectorTiles.org
  • Create by using Tippecanoe on a GeoJSON
• A Mapbox TM2 style folder (Create your own or modify a pre-made style from the Mapbox Github account)

Creating the Custom Style:

1. Download or create an MBTiles file. I suggest using OSM2VectorTiles.org and selecting a nation, region, or city to download.
2. Open Mapbox Studio Classic and click Styles and Sources in the bottom left. Press the New Style or Source button and select one of the 16 starter styles.
3. Configure the starter style to your heart’s content using CartoCSS. In this instance I used Pencil.
4. Find the corresponding open source style (Pencil, in my case) on Mapbox’s Github account and download. I searched Mapbox’s repositories for “pencil” and downloaded the Mapbox-Studio-Pencil.tm2 repository.
5. Copy the CSS from the starter style sheets you customized in Mapbox Studio Classic, (ie style.mss, roads.mss, etc.) and paste the text over the style.mss in the TM2 folder you downloaded from Mapbox’s Github repo using your favorite text editor. For example, I copied my modified CSS from the starter Pencil style, and pasted it over the CSS in the TM2 Pencil style folder I downloaded from Mapbox’s Github.

Serving the Tiles:

1. Open Kitematic, which should have installed with Docker.
2. Search for tileserver-mapnik in Kitematic’s search interface, Install it, and Run it.
3. Once the VM is downloaded and running a Volumes button will appear at bottom right. Click “Enable Volumes” when the dialog appears. This should open the corresponding directory.
4. Paste the MBTILES and TM2 folder you downloaded into the tileserver-mapnik folder that opened in the previous step.
5. Click back to Kitematic and “restart” the Docker container.
6. Click the “Web Preview” box in Kitematic and if all went well it should open a locally running server tab in your browser with a menu.
7. On the menu click the style you uploaded and zoom in to the location of the MBTiles you downloaded to see your handiwork.

Here’s a GIF of the ‘Serving the Tiles’ steps:

Docker makes running a pre-configured virtual machine like Tileserver dead simple. The Tileserver application itself also includes a number of pre-configured examples of how to use your newly-made vector tiles in web services or desktop GIS. Now go forth and customize your basemaps!