Building from Source
We recommend running openrouteservice using a Docker container (see Running with Docker)
- Installation from source
- Running from within IDE
- Installing and running tomcat8
- Integrating GraphHopper
Installation from source
If you need to install without Docker, on an Ubuntu 20.04 system (also generally works with newer Ubuntu versions) you can use the following steps:
- (Fork and) Clone the openrouteservice repository to your machine.
git clone https://github.com/user/openrouteservice.git cd openrouteservice
- Make sure that you have java 1.11 set as the default Java environment.
- Make sure that you have Maven installed.
- Download/create an OpenStreetMap pbf file on the machine.
- Copy the
openrouteservice/src/main/resources/ors-config-sample.jsonfile to the same location but renaming it to
ors-config.json. For testing, use the
- Update the
ors-config.jsonfile to reflect the various settings, profiles you want to have running, and the locations of various files, in particular the source location of the OSM file that will be used and additional files required for extended storages. You should make sure that these folders/files are accessible by the service, for example by using the
sudo chmod -R 777 [path to folder]command. An explanation of the file format and parameters can be found here
- From within the
openrouteservicefolder (containing the pom file and the src folder, amongst others) run the command
mvn package. This will build the openrouteservice ready for tomcat deployment.
After you have packaged openrouteservice, there are two options for running it. One is to run the
mvn spring-boot:run command which triggers a spring-boot native Tomcat instance running on port
8082. This is more restrictive in terms of settings for Tomcat. The other is to install and run Tomcat 8
Running from within IDE
To run the project from within your IDE, you have to:
Set up your IDE project and import
openrouteservice-api-testsmodules as Maven model. For IntelliJ Idea, have a look at these instructions.
Configure your IDE to run
spring-boot:runas the maven goal, setting the environment variable
You can run API tests via JUnit.
Installing and running tomcat8
Install Tomcat 8 using
sudo apt-get install tomcat8.
Note that it might not be available in the lastest repositories of your distribution anymore. In that case, add the following line(s) to your
debian: deb http://ftp.de.debian.org/debian/ stretch main deb http://security.debian.org/ stretch/updates main ubuntu: deb http://de.archive.ubuntu.com/ubuntu bionic main universe deb http://de.archive.ubuntu.com/ubuntu bionic-security main universe
For more details, visit the debian wiki on the
If you want to use system settings (i.e. Java heap size) other than the default, then you need to add these to the
/usr/share/tomcat8/bin/setenv.shfile. If the file is not present, then you can create it. The settings generally used on our servers are similar to:
JAVA_OPTS="-server -XX:TargetSurvivorRatio=75 -XX:SurvivorRatio=64 -XX:MaxTenuringThreshold=3 -XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:ParallelGCThreads=4 -Xms105g -Xmx105g -XX:MaxMetaspaceSize=50m" CATALINA_OPTS="(here we set settings for JMX monitoring)"
- If you add these new settings to the
setenv.shfile, then you need to restart Tomcat for these to take effect using
sudo systemctl restart tomcat8.service.
To get openrouteservice up and running, copy the
ors.warfile found in the
openrouteservice/targetfolder to the Tomcat webapps folder. For example
sudo cp ~/openrouteservice/openroutesrvice/target/ors.war /var/lib/tomcat8/webapps/
- Tomcat should now automatically detect the new WAR file and deploy the service. Depending on profiles and size of the OSM data, this can take some time until openrouteservice has built graphs and is ready for generating routes. You can check if it is ready by accessing
http://localhost:8080/ors/health(the port and URL may be different if you have installed Tomcat differently than above). If you get a
status: readymessage, you are good to go in creating routes.
There are numerous settings within the
ors-config.json which are highly dependent on your individual circumstances, but many of these are documented. As a guide however you can look at the
ors-config-sample.json file in the
openrouteservice/src/main/resources folder. If you run into issues relating to out of memory or similar, then you will need to adjust java/tomcat settings accordingly.
If you need to make adjustments to our forked and edited GraphHopper repository, follow these steps:
Clone and checkout
git clone https://github.com/GIScience/graphhopper.git cd graphhopper git checkout ors_0.13.2
Build the project to create the local snapshot.
<!-- <dependency> <groupId>com.github.GIScience.graphhopper</groupId> <artifactId>graphhopper-core</artifactId> <version>v0.9.12</version> </dependency> <dependency> <groupId>com.github.GIScience.graphhopper</groupId> <artifactId>graphhopper-reader-osm</artifactId> <version>v0.9.12</version> </dependency> --> <dependency> <groupId>com.graphhopper</groupId> <artifactId>graphhopper-core</artifactId> <version>0.13-SNAPSHOT</version> </dependency> <dependency> <groupId>com.graphhopper</groupId> <artifactId>graphhopper-reader-osm</artifactId> <version>0.13-SNAPSHOT</version> </dependency>
Test your new functionality and run
openrouteservice-api-testsafter rebasing your feature branch with the latest
developmentbranch. Adjust tests if necessary
If successful, create a PR for both openrouteservice and GraphHopper against
Note that in these examples, the 0.13_2 version of GH is used - you should update which you use accordingly. To know which to use, check the openrouteservice pom file and see what version is being used for the