Installing Valhalla with Docker

0.3.1 Downloading an OSM extract

The first thing you need is an OpenStreetMap file, in osm.pbf format, of the region you want to work on.

You can download an extract of the OSM data from Geofabrik or BBBike. Planet files are available on https://planet.openstreetmap.org/, but they are very large and not recommended for local use (as they would require a lot of memory).

Create a folder in which to store this file, here we’ll call it “routing-valhalla” (use mkdir routing-valhalla in your terminal to create it). Then, download the OSM extract and move it to this folder.

0.3.2 Running the Docker container

To run the Docker container, you need to run the following command in your terminal (you need to be in the parent folder of the routing-valhalla folder you created earlier, or else you will need to adapt the path to the folder):

docker run -t --name valhalla_server \
    -e build_elevation=True \
    -p 8002:8002 \
    -v $PWD/routing-valhalla:/custom_files \
    ghcr.io/nilsnolde/docker-valhalla/valhalla:latest

Here we are using:

• the -t option to run the container in interactive mode,
• the --name option to name the container valhalla_server,
• the -p option to publish the container’s port 8002 to the host’s port 8002,
• the -v option to mount the folder we created earlier (routing-valhalla) to the /custom_files folder in the container,
• ghcr.io/nilsnolde/docker-valhalla/valhalla:latest image to run the container.

and more importantly,

• the -e option to set the environment variable build_elevation to True, which will build the elevation data for the region.

Other useful options are listed on the image repository.

These include : - build_elevation to download and build elevation data (default: False), this is particularly useful for bicycle and pedestrian routing, - build_admins to build administrative boundaries (default: False), this is useful for applying border-crossing penalties, - build_time_zones to build timezone data (default: False), this is useful for time-dependent routing.

Once the graph is built, you should see a message like this:

INFO: Found config file. Starting valhalla service!

Note that this message is often followed by a several other messages, such as:

[INFO] Tile extract successfully loaded with tile count: 166
[WARN] (stat): /custom_files/traffic.tar No such file or directory
[WARN] Traffic tile extract could not be loaded

This is normal, as we did not provide traffic data to the container (and as traffic data are loaded when the server is started).

You can now access the Valhalla API at http://localhost:8002/ (replace localhost by the IP address of your server if you are running it on a remote server). Go to http://localhost:8002/status in your browser to check that the server is running).

0.3.3 Interacting with the container

To stop the container, you can kill the process running in the terminal (using Ctrl+C), or you can run the following command in another terminal:

docker stop valhalla_server

To restart the container, you can run the following command in your terminal:

docker start valhalla_server

This time the server will start instantly, as the graph has already been built, and the container will run in the background (in detached mode). If needed you can check the logs of the container with:

docker logs valhalla_server

Finally, to totally get rid of the container and the image, you can run the following commands:

docker rm valhalla_server
docker rmi ghcr.io/nilsnolde/docker-valhalla/valhalla:latest