We provide Docker images for various architectures of three images:

• base image: reflects the "plain" image, which contains the whole library & all executables, but no docker-entrypoint script
• scripted image: is based on the "base image" but lets the user configure the whole tile build parameters per environment variables (with sensible defaults) auto-magically, also removes some debugging executables
• dev image: is based on the "base image" and additionally contains everything you need to develop your own applications that consume Valhalla's C++ libraries (most notably the test library as well as googletest)

The "base image" is more catered towards individuals knowing how to configure a Valhalla tile build correctly and wanting to implement non-supported (in the "scripted image") use cases.

The following guide is written for the "scripted image".

# download a file to custom_files and start valhalla
mkdir custom_files
wget -O custom_files/andorra-latest.osm.pbf https://download.geofabrik.de/europe/andorra-latest.osm.pbf
docker run -dt --name valhalla -p 8002:8002 -v $PWD/custom_files:/custom_files ghcr.io/valhalla/valhalla-scripted:latest

# or let the container download the file for you
docker run -dt --name valhalla -p 8002:8002 -v $PWD/custom_files:/custom_files -e tile_urls=https://download.geofabrik.de/europe/andorra-latest.osm.pbf ghcr.io/valhalla/valhalla-scripted:latest

Once built, you can easily change Valhalla's configuration: the underlying OSM graphs are built from, accompanying data (like admin or timezone DBs, elevation tiles etc) or even other pre-built graph tiles. Upon docker restart <container> those changes are taken into account via hashed files, and, if necessary, new graph tiles will be built automatically.

• Easily switch graphs by mapping different volumes to containers.
• Stores all relevant data (tiles, config, admin & timezone DBs, elevation) in the mapped volume.
• Load and build from multiple URLs pointing to valid pbf files. (not recommended)
• Load local data through volume mapping.
• Supports auto rebuild on OSM file changes through md5

If you want to build the image yourself, be aware that you might need to adapt the base image in the Dockerfile to reflect the version of Valhalla you'd like to build. You can find the tags of the ghcr.io/valhalla/valhalla images here: https://github.com/valhalla/valhalla/pkgs/container/valhalla.

Then it's a simple

# optionally build the base image yourself before or download it by default
# docker build -t ghcr.io/valhalla/valhalla:latest .
docker build  -f docker/Dockerfile-scripted -t ghcr.io/valhalla/valhalla-scripted:latest .

The --build-args are:

• VALHALLA_BUILDER_IMAGE: specify the base image, default ghcr.io/valhalla/valhalla:latest

Containers of this image have the following custom environment variables being passed:

For the following instructions to work, you'll need to have the image locally available already, either from Github Docker registry or from local.

Start a background container from that image:

docker run -dt -v $PWD/custom_files:/custom_files -p 8002:8002 --name valhalla ghcr.io/valhalla/valhalla-scripted:latest

The important part here is, that you map a volume from your host machine to the container's /custom_files. The container will dump all relevant Valhalla files to that directory.

At this point Valhalla is running, but there is no graph tiles yet. Follow the steps below to customize your Valhalla instance.

Valhalla supports reading raw GTFS feeds to build transit into its graph, see the docs for more details.

Put the unzipped GTFS feeds as subfolders in the main gtfs folder, e.g. gtfs_feeds/berlin/, otherwise the files will not be found.

To enable multimodal routing, you'll need to map the directory which contains all the GTFS feeds to the container's /gtfs_feeds directory, e.g.

docker run -dt -v gtfs_feeds:/gtfs_feeds -v $PWD/custom_files:/custom_files -p 8002:8002 --name valhalla valhalla/valhalla-scripted:latest

Just dump OSM PBF file(s) to your mapped custom_files directory, restart the container and Valhalla will start building the graphs:

cd custom_files
# Download Andorra & Faroe Islands
wget http://download.geofabrik.de/europe/faroe-islands-latest.osm.pbf http://download.geofabrik.de/europe/andorra-latest.osm.pbf
docker restart valhalla

If you change the PBF files by either adding new ones or deleting any, Valhalla will build new tiles on the next restart unless told not to (e.g. setting use_tiles_ignore_pbf=True).

Elevation tiles need to be in HGT (file format of the SRTM dataset) format and need to be named like NXXEYYY.hgt. More info about format.

You need to store elevation tiles in the <base_path>/elevation_data directory (by default custom_files/elevation_data/). Tiles need to be grouped in folders by latitude , for example:

custom_files/elevation_data/
  N53/
    N53E016.hgt
    N53E017.hgt
  N54/
    N54E016.hgt

If you had an existing graph before you acquired new elevation data, you'll need to rebuild the graph for the new data to become available, e.g. by starting a new container with force_rebuild=True. If you want to use new elevation data for the /height service, you just need to restart the container.

If you need to customize Valhalla's configuration to e.g. increase the allowed maximum distance for the /route service, just edit custom_files/valhalla.json and restart the container. It won't rebuild the tiles in this case, unless you tell it to do so via environment variables.

In the case where you have a pre-built valhalla_tiles.tar package from another Valhalla instance, you can also dump that to /custom_files/ and they're loaded upon container restart if you set the following environment variables: use_tiles_ignore_pbf=True, force_rebuild=False. Also, don't forget to set the md5 sum for your valhalla_tiles.tar in .file_hashes.txt.

If you want to verify that the image is working correctly, there's a small test script in ./tests.

./docker/test.sh