Skip to content

Using a Docker container⚓︎

If you just want to try things out, or you're using an OS other than Ubuntu, and you're using Docker for containerisation, you can try this (thanks to all the contributors there). It's based on the instructions here, but is a pre-built container you can install.

Docker⚓︎

If you don't already have Docker installed, there are lots of "how-tos" around - see for example here.

You'll need around 30GB of disk space for even a small data extract, because the worldwide boundary data that is added to the database is quite large.

OpenStreetmap Data⚓︎

In this example run-through I’ll download data for Zambia and import it, but any OSM .pbf file should work. For testing, try a small .pbf first. When logged in as the non-root user that you run Docker from, download the data for Zambia:

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

Create a docker volume for the data:

docker volume create osm-data

And install it and import the data:

time \
    docker run \
    -v /home/renderaccount/zambia-latest.osm.pbf:/region.osm.pbf \
    -v osm-data:/data/database/ \
    overv/openstreetmap-tile-server import

The path to the data file needs to be the absolute path to the data file - it can't be a relative path. In this example it's in the root directory of the renderaccount user.Also, if something goes wrong, you'll need to docker volume rm osm-data and restart from docker volume create osm-data above. At the end of the process you should see:

INFO:root: Import complete

If you see something like:

/data/region.osm.pbf: Is a directory

or

createuser: error: creation of new role failed: ERROR: role "renderer" already exists

then something has gone wrong; you'll need to use docker ps -a to identify the failed container; docker rm (followed by the container id) to delete it, and then delete and recreate osm-data as described above.

How long this takes depends very much on the local network speed and the size of the area that you are loading. Zambia, used in this example, is relatively small.

Note that if something goes wrong the error messages may be somewhat cryptic, and unfortunately the import process can't be restarted after failure. Also, note that newer versions of the Docker container might use newer versions of postgres, so an osm-data created with an earlier version might not work - you may need to remove it with docker volume rm osm-data and recreate.

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 here, with some minor changes such as the tile URL and the internal account used. Internally you can see that it’s using Ubuntu 22.04. You don’t need to interact with that directly, but you can (via docker exec -it mycontainernumber bash) if you want to.

To start the tile server running:

docker run \
    -p 8080:80 \
    -v osm-data:/data/database \
    -d overv/openstreetmap-tile-server \
    run

and to check that it’s working, from a new incognito window browse to:

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

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

http://your.server.ip.address:8080

for a map that you can zoom in and out of. Tiles (especially at low zoom levels) will take a short period of time to appear.

More Information⚓︎

This docker container actually supports a lot more than the simple example here – see the readme for more details about updates, performance tweaks, etc.

Viewing tiles⚓︎

For a simple “slippy map” that you can modify, you 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 container. 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. Unfortunately, it is necessary to delete and recreate osm-data every time you want to load some new data.