I’ve been wanting to write an explainer for this for a while (even before this diary comment). The problem was that I wasn’t aware of a Docker example that (a) was reasonably up to date and (b) was designed around tile serving (rather than style design for example).

However, this docker example was recently mentioned by its author on IRC. It’s based on the building a tile server for 18.04 instructions and also handles importing data and running the tile server afterwards.

First things first, I installed Centos 7 on a virtual machine. I got a “minimal” iso image for that from here. I installed it (which involved turning the network on inside the installer and selecting the disk to install on). I also set a root password and added a non-root user (I’ll use the example “renderaccount” below), and noted the IP address that it obtained. I did a “yum update” to install any available software updates.

There are a few sets of instructions for “installing Docker on Centos” - DigitalOcean have one, and there’s one here which also contains lots of other useful information. Following the instructions there:

su -
yum install yum-utils device-mapper-persistent-data lvm2 wget
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
yum install docker-ce
systemctl start docker

If you then do this:

systemctl status docker

In the output you should see “active (running)”. Do this:

systemctl enable docker

in order to have docker start every time and then exit from root and do this from you’re non-root user:

sudo usermod -aG docker $USER

So that you can control docker from that non-root user. Log out and back in and do this:

docker container run hello-world

It should say “Hello from Docker!” to show that everything is working OK. If instead you see “permission denied” it probably means you haven’t logged out and back in again.

Next, we’ll follow the openstreetmap-tile-server Docker instructions here. In this example run-through I’ll download data for Zambia and import it, but any OSM .pbf file should work.

When logged in as our non-root user, download the data for Zambia into the root directory of the non-root user:

cd
wget http://download.geofabrik.de/africa/zambia-latest.osm.pbf

Create a docker volume for the data:

docker volume create openstreetmap-data

And install it and import the data:

time docker run -v /home/renderaccount/zambia-latest.osm.pbf:/data.osm.pbf -v openstreetmap-data:/var/lib/postgresql/10/main overv/openstreetmap-tile-server import

Obviously “renderaccount” will need to be changed to the name of your non-root user.

How long this takes depends very much on the local network speed. The largest part of the download will probably be actually the land polygons that OSM’s standard style uses to differentiate land from sea; that file is a fixed size regardless of how large or how small the OSM data file you choose to import is (Zambia, used in this example, is relatively small).

One important thing to note - the path to the .osm.pbf must be the absolute path to the file; it can’t be a relative path. Also note that if something goes wrong the error messages may be somewhat cryptic - you might get “… is a directory” if the data file isn’t found. The “time” at the start of the command isn’t necessary for the installation and import; it just tells you how long it took for future reference.

For more details about what it’s actually doing, have a look at this file. You’ll see that it closely matches the “manually building a tile server” instructions, with some minor changes such as the tile URL and the internal account used. Internally you can see that it’s using Ubuntu 18.04, though you don’t need to interact with that directly.

When the import is complete you should see something like this:

Osm2pgsql took 500s overall

real    157m54.159s
user    0m2.098s
sys     0m0.722s

That tells you how long things took in total (in this case 2.5 hours), and how much of that was spent importing data (6 minutes). The second of these numbers is the rough time that it will take to import data again, since the big data files used by the OSM Carto style have already been downloaded.

To start the tile server running:

docker run -p 80:80 -v openstreetmap-data:/var/lib/postgresql/10/main -d overv/openstreetmap-tile-server run

and to check that it’s working, browse to:

http://your.server.ip.address/tile/0/0/0.png

You should see a map of the world in your browser.

Viewing tiles

For a simple “slippy map” we can use an html file “sample_leaflet.html” which is here in mod_tile’s “extra” folder. Edit “hot” in the URL in that file to read “tile”, and then just open that file in a web browser on the machine where you installed the docker. If that isn’t possible because you’re installing on a server without a local web browser, you’ll also need to edit it to replace “127.0.0.1” with the IP address of the server and copy it to below “/var/www/html” on that server.

If you want to load a different area, just repeat the process from “wget” above. It’ll be quicker the next time because the static data needed by the map style won’t be needed.

If you’re not using Centos

Centos was chosen above mainly because the “mod_tile” software isn’t adapted to run there natively. If using Ubuntu 18.04, you can follow some instructions from DigitalOcean here, or you can install it using “apt”. From a non-root account that has access to “sudo” do this:

sudo add-apt-repository universe
sudo apt update
sudo apt install docker.io
sudo usermod -aG docker $USER

then logout and back in again and:

docker run hello-world

and continue from that stage above.

Acknowledgements

Thanks to the authors of all the guides linked to above, especially the Alexander Overvoorde’s “openstreetmap-tile-server” repository Dockerfile in it, and the (many) original authors of the “building a tile server” instructions.