We provide a docker-compose workflow to install and run local instances of the Overpass API, used to serve data from openstreetmap, and OSRM, used to compute routing distances and durations.
This repository is maintained by the ODISSEI Social Data Science (SoDa) team.
We provide one supported way to install the Overpass API and OSRM servers used in osmenrich
, which makes use of docker-compose
.
We run instances of the Overpass API and of OSRM via Docker
.
- The Overpass API uses the docker image from wiktorn.
- The OSRM instances use the official docker image of the OSRM project: https://hub.docker.com/r/osrm/osrm-backend/.
Note: Docker needs to have at least 4GB of RAM and 2GB of Swap memory available at the time of installation to complete the installation of the overpass API instance. In case your machine does not have enough memory, we suggest you to close the instance(s) of OSRM created using docker-compose to free up memory before trying again.
We assume that docker
is installed and running on your machine. If that is not the case, please head to the Docker website to download Docker Desktop.
Before setting up the server instances using the default settings set by the SoDa science team you need to the setup that most resembles the objective of your project. The table below offers an overview of the choices that we currently provide.
Version | Overpass server/ OSM server |
OSRM server for distances/durations |
Name to use |
---|---|---|---|
Base | Yes | No | base |
Normal car | Yes | Only by car | car |
Normal foot | Yes | Only by foot | foot |
Normal bike | Yes | Only by bike | bike |
Advanced | Yes | Car, foot and bike | advanced |
Once you chose which setup is the most fitting with what required by your project, you need to carry out two steps:
1. Go to the docker folder for the use case you want to setup and modify what comes after the =
for the following variables in the .env
file:
- To select a specific region to use with the OpenStreetMap server, go to https://download.geofabrik.de/ and find the region of interest. Once found, add the name of the country and of the region (or subregion) after the
=
in the following two variable in the.env
file:COUNTRY_MAP=
add name of the countryREGION=
add name of the region or subregion
- Within the same webpage, find the link to the map file that ends with
.osm.bz2
(usually under the sectionOther Formats and Auxiliary Files
) for the country or region you previoulsy selected and copy this link after the=
in the following variable in the.env
file:OVERPASS_PLANET_URL=
add the link to the.osm.bz2
file (usually under the sectionOther Formats and Auxiliary Files
)
- To select the replication server, go to http://download.openstreetmap.fr/replication/ and find the same country or region you selected above. When found, navigate to the
minute
folder and copy the URL after the=
of the following variable:OVERPASS_DIFF_URL=
add the URL of the replication server (needs to end with/minute/
)
2. Then, just use the following commands to download the map and start the containers:
# You need to be in the **root** folder of the repository
cd docker
bash ./build.sh <name-of-the-chose-docker-setup>
1. Follow step 1 of the MacOS or Linux guide with the only difference that you also need to download the <your-location>-latest.osm.pbf
data for your location of interest to docker/osrm/data
from https://download.geofabrik.de/
2. cd
to the folder of your preferred choice of setup, for example cd docker base
3. Then, with Docker Desktop open, start docker compose with docker-compose up
The complete install procedure will take at least one hour. If you run into any problem, please look at the troubleshooting section below or open an issue.
However, we also provided a small guide to manually setup the instances, available here. This guide is not actively supported by the SoDa science team and we recommend to use it only if you know what you are doing and want to have precise control the installation settings for each instance.
-
If Docker complains about not being able to connect to its daemon, make sure you are in the
docker
group:sudo usermod -aG docker $USER
Contributions are what make the open source community an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
In this project we use the
Gitflow workflow
to help us with continious development. Instead of having a single
master
/main
branch we use two branches to record the history of the
project: develop
and master
. The master
branch is used only for the
official releases of the project, while the develop
branch is used to
integrate the new features developed. Finally, feature
branches are used to
develop new features or additions to the project that will be rebased and squash
in the develop
branch.
The workflow to contribute with Gitflow becomes:
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/<AmazingFeature>
) - Commit your Changes (
git commit -m 'Add some <AmazingFeature>'
) - Push to the Branch (
git push origin feature/<AmazingFeature>
) - Open a Pull Request
The osmenrich_docker
repository is published under the MIT license.
Do you have questions, suggestions, or remarks on the technical implementation? File an issue in the issue tracker or feel free to contact Erik-Jan van Kesteren.