From ba7b3b5bf557a0192b8b93f5ba05eed9f611c6ec Mon Sep 17 00:00:00 2001 From: Takara Baumbach Date: Mon, 26 Feb 2024 11:38:03 +0100 Subject: [PATCH] docs: revert to 1 level less in run-instance --- .gitignore | 3 +- docs/.vitepress/config.js | 38 +-- docs/getting-started.md | 2 +- docs/run-instance/building-from-source.md | 62 ++++- docs/run-instance/configuration/index.md | 9 +- docs/run-instance/data.md | 9 +- docs/run-instance/index.md | 70 +++-- .../installation/running-with-docker.md | 226 ---------------- docs/run-instance/jar-docker/build.md | 6 - docs/run-instance/jar-docker/configure.md | 10 - docs/run-instance/jar-docker/download.md | 1 - docs/run-instance/jar-docker/index.md | 4 - docs/run-instance/jar-docker/run.md | 19 -- docs/run-instance/jar-docker/troubleshoot.md | 1 - docs/run-instance/jar/build.md | 28 -- docs/run-instance/jar/configure.md | 1 - docs/run-instance/jar/download.md | 1 - docs/run-instance/jar/index.md | 5 - docs/run-instance/jar/run.md | 1 - docs/run-instance/jar/troubleshoot.md | 1 - docs/run-instance/running-jar.md | 44 +++ docs/run-instance/running-war.md | 54 ++++ docs/run-instance/running-with-docker.md | 252 ++++++++++++++++++ docs/run-instance/system-requirements.md | 11 + docs/run-instance/war-docker/build.md | 7 - docs/run-instance/war-docker/configure.md | 1 - docs/run-instance/war-docker/download.md | 1 - docs/run-instance/war-docker/index.md | 0 docs/run-instance/war-docker/run.md | 1 - docs/run-instance/war-docker/troubleshoot.md | 1 - docs/run-instance/war/build.md | 23 -- docs/run-instance/war/configure.md | 1 - docs/run-instance/war/download.md | 4 - docs/run-instance/war/index.md | 4 - docs/run-instance/war/run.md | 23 -- docs/run-instance/war/troubleshoot.md | 1 - 36 files changed, 478 insertions(+), 447 deletions(-) delete mode 100644 docs/run-instance/installation/running-with-docker.md delete mode 100644 docs/run-instance/jar-docker/build.md delete mode 100644 docs/run-instance/jar-docker/configure.md delete mode 100644 docs/run-instance/jar-docker/download.md delete mode 100644 docs/run-instance/jar-docker/index.md delete mode 100644 docs/run-instance/jar-docker/run.md delete mode 100644 docs/run-instance/jar-docker/troubleshoot.md delete mode 100644 docs/run-instance/jar/build.md delete mode 100644 docs/run-instance/jar/configure.md delete mode 100644 docs/run-instance/jar/download.md delete mode 100644 docs/run-instance/jar/index.md delete mode 100644 docs/run-instance/jar/run.md delete mode 100644 docs/run-instance/jar/troubleshoot.md create mode 100644 docs/run-instance/running-jar.md create mode 100644 docs/run-instance/running-war.md create mode 100644 docs/run-instance/running-with-docker.md delete mode 100644 docs/run-instance/war-docker/build.md delete mode 100644 docs/run-instance/war-docker/configure.md delete mode 100644 docs/run-instance/war-docker/download.md delete mode 100644 docs/run-instance/war-docker/index.md delete mode 100644 docs/run-instance/war-docker/run.md delete mode 100644 docs/run-instance/war-docker/troubleshoot.md delete mode 100644 docs/run-instance/war/build.md delete mode 100644 docs/run-instance/war/configure.md delete mode 100644 docs/run-instance/war/download.md delete mode 100644 docs/run-instance/war/index.md delete mode 100644 docs/run-instance/war/run.md delete mode 100644 docs/run-instance/war/troubleshoot.md diff --git a/.gitignore b/.gitignore index f58bc8455e..a8349fa6d5 100644 --- a/.gitignore +++ b/.gitignore @@ -19,8 +19,7 @@ docker/ # Ignore all ors-config files except for the sample one, useful for development and testing ors-api/src/main/resources/ors-config* -!ors-api/src/main/resources/ors-config-sample.json -ors-api/ors-config.yml +ors-config* envs/ ors-config-repo/ diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 901c43b5db..6bca178dd7 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -96,40 +96,10 @@ export default defineConfig({ items: [ {text: 'System Requirements', link: '/run-instance/system-requirements'}, {text: 'Data', link: '/run-instance/data'}, - {text: 'ORS as JAR', collapsed: true, link: '/run-instance/jar/index.md', - items: [ - {text: 'build', link: '/run-instance/jar/build.md'}, - {text: 'download', link: '/run-instance/jar/download.md'}, - {text: 'configure', link: '/run-instance/jar/configure.md'}, - {text: 'run', link: '/run-instance/jar/run.md'}, - {text: 'troubleshoot', link: '/run-instance/jar/troubleshoot.md'} - ]}, - {text: 'ORS as Docker Container (JAR)', collapsed: true, link: '/run-instance/jar-docker/index.md', - items: [ - {text: 'build', link: '/run-instance/jar-docker/build.md'}, - {text: 'download', link: '/run-instance/jar-docker/download.md'}, - {text: 'configure', link: '/run-instance/jar-docker/configure.md'}, - {text: 'run', link: '/run-instance/jar-docker/run.md'}, - {text: 'troubleshoot', link: '/run-instance/jar-docker/troubleshoot.md'} - ]}, - {text: 'ORS as WAR', collapsed: true, link: '/run-instance/war/index.md', - items: [ - {text: 'build', link: '/run-instance/war/build.md'}, - {text: 'download', link: '/run-instance/war/download.md'}, - {text: 'configure', link: '/run-instance/war/configure.md'}, - {text: 'run', link: '/run-instance/war/run.md'}, - {text: 'troubleshoot', link: '/run-instance/war/troubleshoot.md'} - ]}, - {text: 'ORS as Docker Container (WAR)', collapsed: true, link: '/run-instance/war-docker/index.md', - items: [ - {text: 'build', link: '/run-instance/jar-docker/build.md'}, - {text: 'download', link: '/run-instance/jar-docker/download.md'}, - {text: 'configure', link: '/run-instance/jar-docker/configure.md'}, - {text: 'run', link: '/run-instance/jar-docker/run.md'}, - {text: 'troubleshoot', link: '/run-instance/jar-docker/troubleshoot.md'} - ]}, - {text: 'Building from Source', link: '/run-instance/building-from-source'}, { - }, + {text: 'Running with Docker', link: '/run-instance/running-with-docker'}, + {text: 'Running JAR', link: '/run-instance/running-jar'}, + {text: 'Running WAR', link: '/run-instance/running-war'}, + {text: 'Building from Source', link: '/run-instance/building-from-source'}, { text: 'Configuration', collapsed: true, link: '/run-instance/configuration/', items: [ diff --git a/docs/getting-started.md b/docs/getting-started.md index 2ee40cdcc1..71b23c614f 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -12,7 +12,7 @@ The fastest way to get to the info you are looking for is **the search bar above * [Run ORS instance](run-instance/index.md) contains all info about setting up the ors locally. * [System requirements](run-instance/system-requirements) * [Data](run-instance/data) used by openrouteservice - * [Installation](run-instance/installation/index.md) either directly using [JAR / WAR](run-instance/installation/running-jar-war) artifacts, with [Docker](run-instance/installation/running-with-docker) or [building from source](run-instance/building-from-source.md) + * [Installation](run-instance/installation/index.md) either directly using [JAR / WAR](run-instance/installation/running-jar-war) artifacts, with [Docker](run-instance/running-with-docker.md) or [building from source](run-instance/building-from-source.md) * [Configuration](run-instance/configuration/index.md) of openrouteservice instances * [Contributing](contributing/index.md) contains info about contributing to the openrouteservice, the OpenStreetMap and [translations](contributing/contributing-translations) * [Technical details](technical-details/index.md) contains all sorts of explanation about the internal workings of the openrouteservice. diff --git a/docs/run-instance/building-from-source.md b/docs/run-instance/building-from-source.md index 91015a6008..08e6df5472 100644 --- a/docs/run-instance/building-from-source.md +++ b/docs/run-instance/building-from-source.md @@ -5,19 +5,54 @@ If you need to customize your openrouteservice instance even further than what i ## Prerequisites The following documentation assumes you are running an Ubuntu 20.04 system (also generally works with newer Ubuntu versions). Depending on your environment, you might need to adjust certain details. You will also need to make sure to have the following installed: -* [git](https://github.com/git-guides/install-git) should be available on your system -* [java](https://www.java.com/en/) 17 should be available, preferably as default Java environment -* [maven](https://maven.apache.org/) should be installed on your system +* [java](https://www.java.com/en/) 17 (or higher) should be available, preferably as default Java environment. +* [maven](https://maven.apache.org/) should be installed on your system. +* [git](https://github.com/git-guides/install-git) should be available on your system if you want to download the source code conveniently. -## Get Source Code +## Download source code + +If you have git installed, the easiest way to download the source code is to clone the repository with the following command: -Clone and switch into the repository with the following commands: ```shell -git clone https://github.com/user/openrouteservice.git +git clone https://github.com/GIScience/openrouteservice.git cd openrouteservice ``` -## Running with maven +This creates a directory named `openrouteservice` containing the downloaded source code. All following instructions will assume you are within that directory. + +If you do not have git installed on your system, you can also download the packed (`.zip` and `.tar.gz`) source code file from the "Assets" section of the desired release from our github [releases](https://github.com/GIScience/openrouteservice/releases) page. Unpack the archive and run the following instructions within the directory you unpacked the source code into. + +## Build JAR + +When your source code is set up, you can generate a runnable openrouteservice fat JAR: + +```shell +mvn clean package -PbuildFatJar +``` + +Because JAR is the default, you can also run the command without `-PbuildFatJar`: + +```shell +mvn clean package +``` + +You will find the fat JAR file in `ors-api/target/ors.jar` + +The chapter on [JAR](running-jar.md) artifact explains how to configure and run the JAR file. + +## Build WAR + +When your source code is set up, you can generate a deployable openrouteservice WAR: + +```shell +mvn clean package -PbuildWar +``` + +You will find the WAR file in `ors-api/target/ors.war` + +The chapter on [WAR](running-war.md) artifact explains how to configure and deploy the WAR file. + +## Run source code directly You should be able to run the application directly with @@ -30,10 +65,15 @@ and a small OSM data set from Heidelberg. In [Configuration](configuration/index.md) you find the options how you can use customised configurations. -To create a deployable WAR or JAR artifact, please refer to the documentation for [JAR](jar/build.md) and [WAR](war/build.md). +## For developers + +If you need to customize openrouteservice more than what is possible by [Configuration](configuration/index.md) you might need to make changes to the code. If you implement features that might be useful for others as well, consider [contributing](../contributing/)! + +The following instructions are useful to get you set up to start modifying the code. +### Running from within IDE -## Running from within IDE +[//]: # (TODO: review below here) To run the project from within your IDE, you have to: @@ -47,7 +87,7 @@ To run the project from within your IDE, you have to: 7. You can run all tests via JUnit. -## Running Tests +### Running Tests Running tests is essential if you change the code. Please always make sure that all tests are passing. Failing test sometimes indicate, that code changes break existing code. If the expected behavior of the application changes, it might also be necessary to change existing tests. For new functionality, new tests should be added. @@ -75,7 +115,7 @@ mvn clean package -DskipTests ``` -## Integrating GraphHopper +### Integrating GraphHopper If you need to make adjustments to our forked and edited [GraphHopper repository](https://github.com/GIScience/graphhopper), follow these steps: diff --git a/docs/run-instance/configuration/index.md b/docs/run-instance/configuration/index.md index 281148290f..4217f071b1 100644 --- a/docs/run-instance/configuration/index.md +++ b/docs/run-instance/configuration/index.md @@ -12,7 +12,7 @@ There are two (optional) ways for you to provide openrouteservice the location o export ORS_CONFIG_LOCATION=/path/to/ors-config.yml java -jar ors.jar ``` -If both is specified, the program argument wins. +If both are specified, the program argument wins. [//]: # (TODO: test this) @@ -35,10 +35,9 @@ At program start openrouteservice reports which configuration file was loaded. Depending on the artifact type, the configuration properties can be specified in different formats. Which format to use in which scenario is documented in the config documentations for -[JAR](/run-instance/jar/configure.md), -[WAR](/run-instance/war/configure.md) and -[Docker (JAR)](/run-instance/jar-docker/configure.md) / -[Docker (WAR)](/run-instance/war-docker/configure.md). +[JAR](/run-instance/running-jar.md), +[WAR](/run-instance/running-war.md) and +[Docker](/run-instance/running-with-docker.md). * `.yml` is the default configuration format since version 8. You can find an [example configuration file](https://github.com/GIScience/openrouteservice/blob/main/ors-config.yml) with all available configuration options. Only a minimal set of properties is active, all others are commented out. * `.env` files for Docker setup. There is also a [example env file](https://github.com/GIScience/openrouteservice/blob/main/ors-config.env) that you can download and customize. diff --git a/docs/run-instance/data.md b/docs/run-instance/data.md index 9116c5fdff..8207a29e92 100644 --- a/docs/run-instance/data.md +++ b/docs/run-instance/data.md @@ -1,4 +1,4 @@ -# Folders and Files +# Data: Input and output folders and files ## Input Files @@ -27,6 +27,11 @@ Data relating to the avoid borders features is derived from administrative bound Configuration parameters: [`ors.engine.profiles.*.ext_storages.Borders`](/run-instance/configuration/ors/engine/profiles.md#borders) +### GTFS +The public transport profile integrates [GTFS](https://developers.google.com/transit/gtfs) data for the public transit part. GTFS feeds can be obtained e.g. from sites like https://gtfs.de/ (for Germany), or from local public transport operators. + +Configuration parameters: [`ors.engine.profiles.*.gtfs_file`](/run-instance/configuration/ors/engine/profiles.md) + ### Green & Quiet The data used to identify green and quiet routes were derived from research projects in the GIScience research group at Heidelberg University. More information about these can be found on the GIScience news blog [here](https://giscienceblog.uni-heidelberg.de/2017/07/03/healthy-routing-prefering-green-areas-added-to-openrouteserviceorg/) and [here](http://giscienceblog.uni-heidelberg.de/2017/07/10/reducing-stress-by-avoiding-noise-with-quiet-routing-in-openrouteservice/) @@ -42,7 +47,7 @@ Openrouteservice produces output files of three types, for which the paths can b openrouteservice reads the input data and computes a graph for each enabled routing profile. -The root directory for the graphs can be configured with the configuration property [`graphs_root_path`](/run-instance/configuration/ors/engine/index.md). +The root directory for the graphs can be configured with the configuration property [`ors.engine.graphs_root_path`](/run-instance/configuration/ors/engine/index.md). ### Elevation Cache diff --git a/docs/run-instance/index.md b/docs/run-instance/index.md index 7e30a7bbb0..0c3b69f99e 100644 --- a/docs/run-instance/index.md +++ b/docs/run-instance/index.md @@ -1,32 +1,60 @@ -# Run Your Own openrouteservice Instance +# Running your own openrouteservice instance -If you need to customize the behavior of openrouteservice or if the features or quota provided by our public API is not sufficient for your needs, -you can run your own openrouteservice instance on a server or your local computer. -In an own instance, you can activate all endpoints, also those that are not available in our public API. +If you need to customize the behavior of openrouteservice or if the features or quota provided by our public API is not +sufficient for your needs, you can run your own openrouteservice instance on a server or your local computer. In an own +instance, you can activate all endpoints, also those that are not available in our public API. -There are different options to achieve this. The service can be built in the form of different artifact types: -**WAR**, **JAR** or as **Docker Image** with one of both. In the first column of the table below you find a link to some basic information about each artifact type. +There are different options to achieve this. The service can be built in the form of different artifact types: **WAR**, +**JAR** or as **Docker Image**. In the first column of the table below you find a link to some basic information about +each artifact type. -No matter how you want to run your openrouteservice, you first need the corresponding artifact. -The second and third columns link to detail information about how to build a customized version yourself or where you can download the artifact. +No matter how you want to run your openrouteservice, you first need the corresponding artifact. The second and third +columns link to detail information about how to build a customized version yourself or where you can download the +artifact. -For configuration, operation and troubleshooting it plays no role, -if you run a downloaded or customized version (as long as you don't change basic things like configuration). -You find links to information about these topics in the three right columns. +For configuration, operation and troubleshooting it plays no role, if you run a downloaded or customized version (as +long as you don't change basic things like configuration). You find links to information about these topics in the three +right columns. -But before you start operating your own openrouteservice in the technical way of your choice, -please read the documentation regarding [System Requirements](system-requirements) and [Data](data)! +But before you start operating your own openrouteservice in the technical way of your choice, please read the +documentation regarding [System Requirements](system-requirements) and [Data](data)! - -| Artifact | Build yourself | or Download | Configure | Run | Trouble shoot | -|-------------------------------------------|-------------------------------------------------|-------------------------------------------------------|---------------------------------------------------------|---------------------------------------------|---------------------------------------------------------------| -| [JAR](jar/index.md) | [Build JAR](jar/build.md) | [Download JAR](jar/download.md) | [Configure JAR](jar/configure.md) | [Run JAR](jar/run.md) | [Troubleshoot JAR](jar/troubleshoot.md) | -| [WAR](war/index.md) | [Build WAR](war/build.md) | [Download WAR](war/download.md) | [Configure WAR](war/configure.md) | [Run WAR](war/run.md) | [Troubleshoot WAR](war/troubleshoot.md) | -| [Docker Image (JAR)](jar-docker/index.md) | [Build Docker Image (JAR)](jar-docker/build.md) | [Download Docker Image (JAR)](jar-docker/download.md) | [Configure Docker Image (JAR)](jar-docker/configure.md) | [Run Docker Image (JAR)](jar-docker/run.md) | [Troubleshoot Docker Image (JAR)](jar-docker/troubleshoot.md) | -| [Docker Image (WAR)](war-docker/index.md) | see [older versions](...?) | no longer supported since version 8 | [Configure Docker Image (WAR)](war-docker/configure.md) | [Run docker (WAR)](war-docker/run.md) | [Troubleshoot docker (WAR)](war-docker/troubleshoot.md) | +| Artifact | Download | or build yourself | Run | Configure | Trouble shoot | +|----------------------------------------|-------------------------------------------------------------------------|----------------------------------------------------------|---------------------------------------------------------------------|------------------------------------------------------------|------------------------------------------------------------------| +| [JAR](running-jar.md) | [Download JAR](running-jar.md#download) | [Build JAR](building-from-source.md#build-jar) | [Run JAR](running-jar.md#run) | [Configure JAR](running-jar.md#configure) | [Troubleshoot JAR](running-jar.md#troubleshoot) | +| [WAR](running-war.md) | [Download WAR](running-war.md#download) | [Build WAR](building-from-source.md#build-war) | [Run WAR](running-war.md#run) | [Configure WAR](running-war.md#configure) | [Troubleshoot WAR](running-war.md#troubleshoot) | +| [Docker Image](running-with-docker.md) | [Download Docker Image](running-with-docker.md#running-prebuilt-images) | [Build Docker Image](running-with-docker.md#build-image) | [Run Docker Image](running-with-docker.md#running-prebuilt-images) | [Configure Docker Image](running-with-docker.md#configure) | [Troubleshoot Docker Image](running-with-docker.md#troubleshoot) | +| [Source code](building-from-source.md) | [Download source code](building-from-source.md#download-source-code) | | [Run source code](building-from-source.md#run-source-code-directly) | [Configure](building-from-source.md#configure) | | [//]: # (TODO add row for rpm package once integrated) ::: tip -We recommend to use one of the JAR options, plain or with docker. +We recommend to use the docker option for simplicity, or plain JAR if you do not want to install Docker. ::: + +## Checking + +By default, the service status can be queried via the [health endpoint](/api-reference/endpoints/health/index.md). + +```shell +curl 'http://localhost:8080/ors/v2/health' +# should result in an output like +# {"status":"ready"} +``` + +When the service is ready, you will be able to request the [status endpoint](/api-reference/endpoints/status/index.md) +for further information on the running services. + +```shell +curl 'http://localhost:8080/ors/v2/status' +# should result in an output like +# {"languages":["cs","cs-cz","de","de-de","en","en-us","eo","eo-eo","es","es-es","fr","fr-fr","gr","gr-gr","he","he-il","hu","hu-hu","id","id-id","it","it-it","ja","ja-jp","ne","ne-np","nl","nl-nl","pl","pl-pl","pt","pt-pt","ro","ro-ro","ru","ru-ru","tr","tr-tr","zh","zh-cn"],"engine":{"build_date":"2024-01-02T16:34:45Z","version":"8.0"},"profiles":{"profile 1":{"storages":{"WayCategory":{"gh_profile":"car_ors_fastest_with_turn_costs"},"HeavyVehicle":{"gh_profile":"car_ors_fastest_with_turn_costs"},"WaySurfaceType":{"gh_profile":"car_ors_fastest_with_turn_costs"},"RoadAccessRestrictions":{"gh_profile":"car_ors_fastest_with_turn_costs","use_for_warnings":"true"}},"profiles":"driving-car","creation_date":"","limits":{"maximum_distance":100000,"maximum_waypoints":50,"maximum_distance_dynamic_weights":100000,"maximum_distance_avoid_areas":100000}}},"services":["routing","isochrones","matrix","snap"]} +``` + +If you use the default dataset you will be able to request something like the following route request to the car profile +in Heidelberg. + +```shell +curl 'http://localhost:8080/ors/v2/directions/driving-car?start=8.681495,49.41461&end=8.687872,49.420318' +``` + diff --git a/docs/run-instance/installation/running-with-docker.md b/docs/run-instance/installation/running-with-docker.md deleted file mode 100644 index 4160a027af..0000000000 --- a/docs/run-instance/installation/running-with-docker.md +++ /dev/null @@ -1,226 +0,0 @@ -# Running with Docker - -## Install and run openrouteservice with Docker - -Installing the openrouteservice backend service with Docker is quite straightforward. All you need is an OSM extract, e.g. from [Geofabrik](http://download.geofabrik.de), and a working [Docker installation](https://www.digitalocean.com/community/tutorial_collections/how-to-install-and-use-docker). - -You can use [Docker Hub's hosted Openrouteservice image](https://hub.docker.com/repository/docker/openrouteservice/openrouteservice) or build your own image. - -> For a step-by-step guide also check out [this YouTube video](https://www.youtube.com/watch?v=VQXlbqKArFk) (Thanks a lot SyntaxByte <3), though it is a bit outdated by now... - -## Docker scenarios - -There are multiple ways with Docker to quickly have a running instance. - -1. Recommended: Run latest release version image using `docker compose` - - ```shell - # For latest build - wget https://raw.githubusercontent.com/GIScience/openrouteservice/main/docker-compose.yml - docker compose up -d - ``` - -2. Run specific version image using `docker compose` - - You can specify the Docker image tag by declaring an environment variable named `ORS_TAG`. Possible values are specific version tags such as `v7.2.0` or `nightly` for the newest nightly build. - - ```shell - # For nightly builds - wget https://raw.githubusercontent.com/GIScience/openrouteservice/main/docker-compose.yml - export ORS_TAG=nightly && docker compose up -d - ``` - -3. Run a Docker image built from local code - - It is also possible to compile local code and build a Docker image to run. This can be useful in cases where you want to use a version of openrouteservice with modified code. - - ```shell - # Download entire source code - git clone https://github.com/GIScience/openrouteservice.git - cd openrouteservice - ``` - - After downloading the code, open the file `docker-compose.yml`, remove line 8 and uncomment lines 11-14. - - ::: details Click here to see the code - - ```yaml - version: '2.4' - services: - ors-app: - container_name: ors-app - ports: - - "8080:8080" - - "9001:9001" - image: openrouteservice/openrouteservice:nightly // [!code --] - # For versioned images see https://giscience.github.io/openrouteservice/run-instance/installation/running-with-docker - user: "${UID:-0}:${GID:-0}" - # build: // [!code --] - # context: ./ // [!code --] - # args: // [!code --] - # OSM_FILE: ./ors-api/src/test/files/heidelberg.osm.gz // [!code --] - build: // [!code ++] - context: ./ // [!code ++] - args: // [!code ++] - OSM_FILE: ./ors-api/src/test/files/heidelberg.osm.gz // [!code ++] - volumes: - - ./docker/graphs:/home/ors/ors-core/data/graphs - [...] - ``` - ::: - - This tells Docker to build the local code using maven and build a Docker image with that code instead of pulling the ready-built image from Docker Hub. You can then build and start the image with the following command. - - ```shell - # After modifying the docker-compose.yml file - docker compose up -d - ``` - -4. `docker run` for ors versions >= 6.8.2 - - You can specify the entire Docker command (that `docker compose` would run for you) if you need to change specific details. It is easier to modify the Docker compose file, but to test a specific setup you can run the following command. To use a different version of openrouteservice, change the tag (after the colon) in the last line. - - ```shell - # create directories for volumes to mount as local user - mkdir -p docker/conf docker/elevation_cache docker/graphs docker/logs/ors docker/logs/tomcat - docker run -dt -u "${UID}:${GID}" \ - --name ors-app \ - -p 8080:8080 \ - -v $PWD/docker/graphs:/home/ors/ors-core/data/graphs \ - -v $PWD/docker/elevation_cache:/home/ors/ors-core/data/elevation_cache \ - -v $PWD/docker/logs/ors:/home/ors/ors-core/logs/ors \ - -v $PWD/docker/logs/tomcat:/home/ors/tomcat/logs \ - -v $PWD/docker/conf:/home/ors/ors-conf \ - -v $PWD/docker/data:/home/ors/ors-core/data \ - #-e "BUILD_GRAPHS=True" \ - -e "JAVA_OPTS=-Djava.awt.headless=true -server -XX:TargetSurvivorRatio=75 -XX:SurvivorRatio=64 -XX:MaxTenuringThreshold=3 -XX:+UseG1GC -XX:+ScavengeBeforeFullGC -XX:ParallelGCThreads=4 -Xms1g -Xmx2g" \ - -e "CATALINA_OPTS=-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9001 -Dcom.sun.management.jmxremote.rmi.port=9001 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=localhost" \ - openrouteservice/openrouteservice:latest - ``` - -5. `docker run` for ors versions <= 6.8.1 - - For older versions of openrouteservice, the Dockerfile has a different internal directory structure, and the `docker compose` file will not yield the same result. Use the following `docker` command instead. - - ```bash - # create directories for volumes to mount as local user - mkdir -p docker/conf docker/elevation_cache docker/graphs docker/logs/ors docker/logs/tomcat - docker run -dt -u "${UID}:${GID}" \ - --name ors-app \ - -p 8080:8080 \ - -v $PWD/docker/graphs:/ors-core/data/graphs \ - -v $PWD/docker/elevation_cache:/ors-core/data/elevation_cache \ - -v $PWD/docker/logs/ors:/home/ors/ors-core/logs/ors \ - -v $PWD/docker/logs/tomcat:/home/ors/tomcat/logs \ - -v $PWD/docker/conf:/ors-conf \ - -v $PWD/docker/data:/ors-core/data \ - #-e "BUILD_GRAPHS=True" \ - -e "JAVA_OPTS=-Djava.awt.headless=true -server -XX:TargetSurvivorRatio=75 -XX:SurvivorRatio=64 -XX:MaxTenuringThreshold=3 -XX:+UseG1GC -XX:+ScavengeBeforeFullGC -XX:ParallelGCThreads=4 -Xms1g -Xmx2g" \ - -e "CATALINA_OPTS=-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9001 -Dcom.sun.management.jmxremote.rmi.port=9001 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=localhost" \ - openrouteservice/openrouteservice:v6.8.1 - ``` - -## Checking - -By default, the service status can be queried via the [health endpoint](/api-reference/endpoints/health/index.md). - -```shell -curl 'http://localhost:8080/ors/v2/health' -# should result in an output like -# {"status":"ready"} -``` - -When the service is ready, you will be able to request the [status endpoint](/api-reference/endpoints/status/index.md) for further information on the running services. - -```shell -curl 'http://localhost:8080/ors/v2/status' -# should result in an output like -# {"languages":["cs","cs-cz","de","de-de","en","en-us","eo","eo-eo","es","es-es","fr","fr-fr","gr","gr-gr","he","he-il","hu","hu-hu","id","id-id","it","it-it","ja","ja-jp","ne","ne-np","nl","nl-nl","pl","pl-pl","pt","pt-pt","ro","ro-ro","ru","ru-ru","tr","tr-tr","zh","zh-cn"],"engine":{"build_date":"2024-01-02T16:34:45Z","version":"8.0"},"profiles":{"profile 1":{"storages":{"WayCategory":{"gh_profile":"car_ors_fastest_with_turn_costs"},"HeavyVehicle":{"gh_profile":"car_ors_fastest_with_turn_costs"},"WaySurfaceType":{"gh_profile":"car_ors_fastest_with_turn_costs"},"RoadAccessRestrictions":{"gh_profile":"car_ors_fastest_with_turn_costs","use_for_warnings":"true"}},"profiles":"driving-car","creation_date":"","limits":{"maximum_distance":100000,"maximum_waypoints":50,"maximum_distance_dynamic_weights":100000,"maximum_distance_avoid_areas":100000}}},"services":["routing","isochrones","matrix","snap"]} -``` - -If you use the default dataset you will be able to request something like the following route request to the car profile in Heidelberg. - -```shell -curl 'http://localhost:8080/ors/v2/directions/driving-car?start=8.681495,49.41461&end=8.687872,49.420318' -``` - -## Docker configuration - -Running openrouteservice out of the box via Docker and docker-compose is a great way to quickly get into how to use openrouteservice. For most applications though, you would want to customise some things such as which profiles you want to build and the data that you want to route with. In its initial Docker container form, openrouteservice uses an older test dataset of Heidelberg (Germany) as the base data, and only builds the car profile. To do more than that, you need to get your hands a little dirty with some configuration settings. This may sound a little daunting, but it is designed in a way that once you overcome the initial understanding of the configuration and Docker, you will be able to use your own datasets and decide which profiles to use in no time. - -### What you get - -All the above scenarios will: - -1. Pull the openrouteservice Docker image from Docker Hub and start a container named `ors-app` -2. Launch the openrouteservice service on port `8080` within a tomcat running in that container, available at the address `http://localhost:8080/ors`. -3. Create a local `./docker` folder containing the files used and produced by openrouteservice for easy access. Most relevant is `./docker/conf/ors-config.yml` controlling ORS behaviour, and the test OSM data file `/home/ors/ors-core/data/osm_file.pbf` of Heidelberg and surroundings. - -### Customization - -Once you have a built image you can decide to start a container with different settings, e.g. changing the active profiles or other settings. To run ORS with a custom configuration, modify the `./docker/conf/ors-config.yml` to your needs, and restart the container. You can obviously also modify the volume mappings in the `docker-compose.yml` to your needs. **Note that using `docker-compose restart` does not carry across changes made inside the `docker-compose.yml` file, so you should use `docker-compose down` to take down the container, and then `docker-compose up` to restart it again when you have made changes.** - -For detailed information on the settings you can make, see the chapter on [configuration](/run-instance/configuration/index.md). - -Old ORS configuration files in JSON format are **deprecated**. If you have a custom `ors-config.json` file from a previous installation we strongly recommend to migrate to the new YAML format. For the transitional period ORS allows the use of old format JSON files placed at `./docker/conf/ors-config.json`. All settings in such a file, if present, will override settings in the proper YAML format. - -If you are making changes to anything relating to the OSM data or the settings that change how graphs are built, you need to delete the folders in `graphs` or set the environment variable `BUILD_GRAPHS=True` (see comment in Dockerfile or examples above). This makes it so that the graphs are built again with the new data/settings. - -### Different OSM file -To change the OSM data that is used, you can either overwrite the `docker/data/osm_file.pbf` file, or modify the volume mount of `/home/ors/ors-core/data` to a directory containing a file `osm_file.pbf`, or volume mount something like `/YOUR/PATH/TO/ANOTHER/OSM_FILE.pbf:/home/ors/ors-core/data/osm_file.pbf`. - -Make sure to set the environment variable `BUILD_GRAPHS=True` or empty the `docker/graphs/` directory before restarting the container. - -If you are building the Docker image locally, you can also point the build argument `OSM_FILE` to your desired OSM file before building the image. - -Note, `.osm`, `.osm.gz`, `.osm.zip` and `.pbf` file format are supported as OSM files. - -If your dataset is very large, it may be necessary to adjust the `-Xmx` parameter of `JAVA_OPTS` environment variable. A good rule of thumb is to give Java 2 x file size of the PBF **per profile**. - -::: details Further info on memory settings -In the `JAVA_OPTS` line of the `docker-compose.yml` file, you will see the `-Xms1g` and `-Xmx2g` items. These tell Java that it should start with 1GB RAM assigned to it, and go no higher than 2 GB of usage. If let's say your pbf file is 1.5 GB in size, and you have two profiles configured (e.g. car and foot-walking), then you would update the `-Xmx` item to be **AT LEAST** `-Xmx6g` (1.5GB * 2 Profiles * 2). In general, we would recommend adding a bit more to the RAM value if possible to reduce the chances of hitting an out of memory exception towards the end of the graph building. -::: - -### UID - -If you need to change the UID the ors is running with, you can use these variables: -```bash -# set it explicitly to 1001 -ORS_UID=1001 ORS_GID=1001 docker compose up -d - -# or set it to the current user -ORS_UID=${UID} ORS_GID=${GID} docker compose up -d -``` - -### Volumes - -There are some important directories one might want to preserve on the host machine, to survive container regeneration. These directories should be mapped as volumes. - -- `/home/ors/ors-core/data/graphs`: Contains the built graphs after ORS initialized. -- `/home/ors/ors-core/data/elevation_cache`: Contains the CGIAR elevation tiles if elevation was specified. -- `/home/ors/ors-core/logs/ors`: Contains the ORS logs. -- `/home/ors/tomcat/logs`: Contains the Tomcat logs. -- `/home/ors/ors-conf`: Contains the `ors-config.json` which is used to control ORS. -- `/home/ors/ors-core/data`: Contains the OSM file `osm_file.pbf` being used to generate graphs. - -Look at the [`docker-compose.yml`](https://github.com/GIScience/openrouteservice/blob/main/docker-compose.yml) for examples. - -### Environment variables - -- `BUILD_GRAPHS`: Forces ORS to rebuild the routing graph(s) when set to `True`. Useful when another PBF is specified in the Docker volume mapping to `/home/ors/ors-core/data/osm_file.pbf` -- `JAVA_OPTS`: Custom Java runtime options, such as `-Xms` or `-Xmx` -- `CATALINA_OPTS`: Custom Catalina options - -Specify either during container startup or in `docker-compose.yml`. - -### Build arguments - -When building the image, the following arguments are customizable: - -- `ORS_CONFIG`: Can be changed to specify the location of a custom `ors-config.json` file. Default `./ors-api/src/main/resources/ors-config.json`. -- `OSM_FILE`: Can be changed to point to a local custom OSM file. Default `./ors-api/src/test/files/heidelberg.osm.gz`. - -## Instance infrastructure -Though having a single container works great for smaller datasets or when the graph data doesn't need updating, in many real world implementations having just the one instance isn't the most suitable solution. If you have one container, then all building and serving of routes happens through that single container, meaning that when you rebuild graphs, you can't make any requests to that instance for things like directions as there are no complete graphs that can be used to generate routes with. If it is important that you have graph updates from new data whilst ensuring that there is a minimal amount of time during which users cannot make requests, we would recommend having two instances - one that is permanently active for serving requests, and one that gets fired up to rebuild graphs. - -In that setup, when graphs have been built you can simply stop the container serving requests, replace the graphs used (they are mapped to a folder on the host machine which is defined in the `docker-compose` file), and then restart the container. The new graphs will be reloaded into memory (the amount of time needed for this depends on the size of the graphs and the type of hard drive) and then ready to use for routing. The downtime from reloading already built graphs is normally far less than the time needed to build the graphs. A thing to note though is that you should ensure that the config files and the amount of RAM allocated (as described earlier) is the same on both the builder and the request server else the newly built graphs may not load. **Also, ensure that `BUILD_GRAPHS` parameter in the `docker-compose` file used by the request serving container is set to false else it will try to build the graphs for itself!** diff --git a/docs/run-instance/jar-docker/build.md b/docs/run-instance/jar-docker/build.md deleted file mode 100644 index 204f04bfbf..0000000000 --- a/docs/run-instance/jar-docker/build.md +++ /dev/null @@ -1,6 +0,0 @@ -# Build Docker Image with openrouteservice JAR - -::: tip Hint -If you don't need changes in the code, you don't need to build the artifact yourself. If this is the case, skip this page and go to [download](download.md). -::: - diff --git a/docs/run-instance/jar-docker/configure.md b/docs/run-instance/jar-docker/configure.md deleted file mode 100644 index 30706e6bc9..0000000000 --- a/docs/run-instance/jar-docker/configure.md +++ /dev/null @@ -1,10 +0,0 @@ -# Configure Docker Image with openrouteservice JAR - - -## With Environment file - -The recommended way to configure - -## With mounted Config file - -Another way is to... \ No newline at end of file diff --git a/docs/run-instance/jar-docker/download.md b/docs/run-instance/jar-docker/download.md deleted file mode 100644 index a3e51dc436..0000000000 --- a/docs/run-instance/jar-docker/download.md +++ /dev/null @@ -1 +0,0 @@ -# Download Docker Image with openrouteservice JAR \ No newline at end of file diff --git a/docs/run-instance/jar-docker/index.md b/docs/run-instance/jar-docker/index.md deleted file mode 100644 index fd40910d9e..0000000000 --- a/docs/run-instance/jar-docker/index.md +++ /dev/null @@ -1,4 +0,0 @@ - - - - diff --git a/docs/run-instance/jar-docker/run.md b/docs/run-instance/jar-docker/run.md deleted file mode 100644 index 5b5a9ca421..0000000000 --- a/docs/run-instance/jar-docker/run.md +++ /dev/null @@ -1,19 +0,0 @@ -# Run Docker Image with openrouteservice JAR - - - -## With docker compose - -The fastest and easiest way to have an instance of openrouteservice running is to use our docker compose file. If you have docker installed, running the following commands should get everything done. - -```shell -wget https://raw.githubusercontent.com/GIScience/openrouteservice/main/docker-compose.yml -docker compose up -``` - -This will pull the latest nightly build of openrouteservice from Docker Hub and start it up using an example setup and the provided test OSM file for Heidelberg/Germany and surrounding area. -You can then modify the configuration and source file settings to match your needs. For more details, check the [Running with Docker](installation/running-with-docker) section. - - - -## With docker run diff --git a/docs/run-instance/jar-docker/troubleshoot.md b/docs/run-instance/jar-docker/troubleshoot.md deleted file mode 100644 index 20fcce05f2..0000000000 --- a/docs/run-instance/jar-docker/troubleshoot.md +++ /dev/null @@ -1 +0,0 @@ -# Troublelshoot Docker Image with openrouteservice JAR \ No newline at end of file diff --git a/docs/run-instance/jar/build.md b/docs/run-instance/jar/build.md deleted file mode 100644 index 68e07c8fe2..0000000000 --- a/docs/run-instance/jar/build.md +++ /dev/null @@ -1,28 +0,0 @@ -# Build openrouteservice JAR - - -::: tip Hint -If you don't need changes in the code, you don't need to build the artifact yourself. If this is the case, skip this page and go to [download](download.md). -::: - -First checkout the openrouteservice repository and setup your local project. -How this is done is independent of the artifact type you want to use and is documented in [Building from Source](/run-instance/building-from-source.md). -There you will also learn how to carry out tests, which is essential for code changes. - -When your project is set up, you can generate a runnable openrouteservice fat JAR: -```shell -mvn clean package -PbuildFatJar -``` - -Because JAR is the default, you can also run the command without `-PbuildFatJar`: -```shell -mvn clean package -``` - -You will find the fat JAR in - -```shell -ors-api/target/ors.jar -``` - -Read in the next chapters how to configure and run the jar. diff --git a/docs/run-instance/jar/configure.md b/docs/run-instance/jar/configure.md deleted file mode 100644 index 5785be35d4..0000000000 --- a/docs/run-instance/jar/configure.md +++ /dev/null @@ -1 +0,0 @@ -# Configure openrouteservice JAR \ No newline at end of file diff --git a/docs/run-instance/jar/download.md b/docs/run-instance/jar/download.md deleted file mode 100644 index bed0bfd608..0000000000 --- a/docs/run-instance/jar/download.md +++ /dev/null @@ -1 +0,0 @@ -# Download openrouteservice JAR \ No newline at end of file diff --git a/docs/run-instance/jar/index.md b/docs/run-instance/jar/index.md deleted file mode 100644 index 03da6c0b7f..0000000000 --- a/docs/run-instance/jar/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# openrouteservice as JAR - -Since version 8, openrouteservice can be built as a fat JAR, that contains all its dependencies. -The JAR can be started stand-alone, without an installed tomcat. -The trick is, that an embedded servlet container (tomcat) is used. \ No newline at end of file diff --git a/docs/run-instance/jar/run.md b/docs/run-instance/jar/run.md deleted file mode 100644 index 0c038bc801..0000000000 --- a/docs/run-instance/jar/run.md +++ /dev/null @@ -1 +0,0 @@ -# Run openrouteservice JAR \ No newline at end of file diff --git a/docs/run-instance/jar/troubleshoot.md b/docs/run-instance/jar/troubleshoot.md deleted file mode 100644 index fc9ebcc7f0..0000000000 --- a/docs/run-instance/jar/troubleshoot.md +++ /dev/null @@ -1 +0,0 @@ -# Troubleshoot openrouteservice JAR \ No newline at end of file diff --git a/docs/run-instance/running-jar.md b/docs/run-instance/running-jar.md new file mode 100644 index 0000000000..29d0b137ff --- /dev/null +++ b/docs/run-instance/running-jar.md @@ -0,0 +1,44 @@ +# Running openrouteservice as JAR + +Since version 8, openrouteservice can be built as a fat JAR file that contains all its dependencies and can be run as stand-alone application. + +::: tip Hint +If you have Docker installed on your system, it is more convenient to run a [Docker Image](running-with-docker.md) instead. +If you have Tomcat installed on your system, it may be convenient to run a [WAR](running-war.md) file within that Tomcat instance instead. +::: + +## Prerequisites + +* [java](https://www.java.com/en/) 17 (or higher) should be available, preferably as default Java environment. + +To run openrouteservice, you also need an OSM data file, e.g. from [Geofabrik](http://download.geofabrik.de). For more details, see chapter [Data](data.md). + +## Download + +Starting with version 8 you can download the ready to use JAR file from the "Assets" section of the desired release from our github [releases](https://github.com/GIScience/openrouteservice/releases) page. + +## Build + +How this is done is independent of the artifact type you want to use and is documented in [Building from Source](/run-instance/building-from-source.md). + +## Run + +To run the openrouteservice application, use the following command: + +```shell +java -jar ors.jar +``` + +## Configure + +The recommended way to configure an openrouteservice instance run plain using the JAR file is to use a YAML configuration file. You can download an example file by using the following command: + +```shell +wget https://raw.githubusercontent.com/GIScience/openrouteservice/main/ors-config.yml +``` + +For details on how to make openrouteservice apply the settings in the configuration file (there are multiple options) see chapter [Configuration](configuration/). + +## Troubleshoot + + diff --git a/docs/run-instance/running-war.md b/docs/run-instance/running-war.md new file mode 100644 index 0000000000..d7d1d48ab9 --- /dev/null +++ b/docs/run-instance/running-war.md @@ -0,0 +1,54 @@ +# Running openrouteservice as WAR + +Like older versions, ORS version 8 can still be built and run as a Web Application Resource aka Web ARchive (WAR). +A WAR file can be deployed to a Servlet Container like Tomcat, which is running as a service. +To run openrouteservice, you also need an OSM data file, e.g. from [Geofabrik](http://download.geofabrik.de). For more details see chapter [Data](data.md). + + +::: tip Hint +If you have Docker installed on your system, it may be more convenient to run a [Docker Image](running-with-docker.md) instead. +If you do not have Tomcat installed on your system, it is more convenient to run a plain [JAR](running-jar.md) file instead. +::: + +## Prerequisites + +* [Tomcat](https://tomcat.apache.org/) 10 (or higher) should be installed. E.g. on Ubuntu 22.04, follow these [instructions](https://linuxize.com/post/how-to-install-tomcat-10-on-ubuntu-22-04/). + +To run openrouteservice, you also need an OSM data file, e.g. from [Geofabrik](http://download.geofabrik.de). For more details, see chapter [Data](data.md). + +## Download + +Starting with version 8 you can download the ready to use WAR from the "Assets" section of the desired release from our github [releases](https://github.com/GIScience/openrouteservice/releases) page. + +## Build + +How this is done is independent of the artifact type you want to use and is documented in [Building from Source](/run-instance/building-from-source.md). + +## Run + +Running a WAR file means deploying it to a Tomcat instance. To get openrouteservice up and running, simply copy the `ors.war` file to the Tomcat webapps folder. Tomcat should now automatically detect the new WAR file and deploy the service. + +## Configure + +When deploying openrouteservice within Tomcat, there are some important differences to note: +- The recommended way to pass instructions to openrouteservice is to use environment variables. You need to add these to the `setenv.sh` file in your tomcat bin folder, typically somewhere like `/usr/share/tomcat10/bin/`. If the file is not present, then you can create it. +- If you add new settings to the `setenv.sh` file, then you need to restart Tomcat for these to take effect using a command like `sudo systemctl restart tomcat.service`. +- Your configuration file and all input / output files and directories referenced by that configuration need to be accessible (and in case of the output folders, writable) to the user your Tomcat instance is running as. You might need to adjust the location of said files and folders or `chmod` / `chown` them accordingly. + +The recommended way to configure an openrouteservice instance is to use a YAML configuration file. You can download an example file by using the following command: + +```shell +wget https://raw.githubusercontent.com/GIScience/openrouteservice/main/ors-config.yml +``` + +Then you need to add an environment variable to your `setenv.sh` pointing to that configuration file: + +```shell +ORS_CONFIG_LOCATION=/path/to/ors-config.yml +``` + +For details on how to make openrouteservice apply the settings in the configuration file (there are multiple options) see chapter [Configuration](configuration/). + +## Troubleshoot + + diff --git a/docs/run-instance/running-with-docker.md b/docs/run-instance/running-with-docker.md new file mode 100644 index 0000000000..8b9352e11a --- /dev/null +++ b/docs/run-instance/running-with-docker.md @@ -0,0 +1,252 @@ +# Running with Docker + +If Docker is available on your system, openrouteservice can be run within a container using prebuilt images from [dockerhub](https://hub.docker.com/r/openrouteservice/openrouteservice) or by building your own image from our source files. + +::: tip Hint +If you do not have Docker installed on your system, it is more convenient to run a plain [JAR](running-jar.md) file instead. +If you have Tomcat installed on your system, it may be convenient to run a [WAR](running-war.md) file within that Tomcat instance instead. +::: + +## Prerequisites + +* [Docker](https://docs.docker.com/get-docker/) should be installed on your system. + +## Running prebuilt images + +There are multiple ways with Docker to quickly have a running instance. + +1. Recommended: Run latest release version image using `docker compose` + + ```shell + # For latest release build + wget https://raw.githubusercontent.com/GIScience/openrouteservice/main/docker-compose.yml + docker compose up -d + ``` + This will pull the latest release build of openrouteservice from Docker Hub and start it up using an example setup + and the provided test OSM file for Heidelberg/Germany and surrounding area. + +2. Run specific version image using `docker compose` + + You can specify the Docker image tag by declaring an environment variable named `ORS_TAG`. Possible values are + specific version tags such as `v8.0.0` or `nightly` for the newest nightly build. + + ```shell + # For nightly builds + wget https://raw.githubusercontent.com/GIScience/openrouteservice/main/docker-compose.yml + export ORS_TAG=nightly && docker compose up -d + ``` + +## Build image + +To build your own image, you need to download the source code by following the instructions in chapter [Building from Source](/run-instance/building-from-source.md#download-source-code). You do not have to have Java or Maven installed on your system. + +After downloading the source, you can build your Docker image by running the following command in the source directory: + +```shell +docker build . -t openrouteservice/openrouteservice:local +``` + +You should now have a local docker image which you can verify by running `docker image ls`. +You can then run your instance by running: + +```shell +export ORS_TAG=local && docker compose up -d +``` + +::: details Alternative: modify docker compose to build image + +After downloading the code, open the file `docker-compose.yml`, remove line 8 and uncomment lines 11-14. + +```yaml +version: '2.4' +services: + ors-app: + container_name: ors-app + ports: + - "8080:8080" + - "9001:9001" + image: openrouteservice/openrouteservice:nightly // [!code --] + # For versioned images see https://giscience.github.io/openrouteservice/run-instance/installation/running-with-docker + user: "${UID:-0}:${GID:-0}" +# build: // [!code --] +# context: ./ // [!code --] +# args: // [!code --] +# OSM_FILE: ./ors-api/src/test/files/heidelberg.osm.gz // [!code --] + build: // [!code ++] + context: ./ // [!code ++] + args: // [!code ++] + OSM_FILE: ./ors-api/src/test/files/heidelberg.osm.gz // [!code ++] + volumes: + - ./docker/graphs:/home/ors/ors-core/data/graphs +[...] +``` + +This causes Docker to build the image with the local code instead of pulling the +ready-built image from Docker Hub. +You can then build and start the image with the following command. + + ```shell + # After modifying the docker-compose.yml file + docker compose up -d + ``` +::: + +## Running without docker compose + +You can specify the entire Docker command (that `docker compose` would run for you) if you need to change specific +details. +It is easier to modify the Docker compose file, but to test a specific setup, you could run the following +command. To use a different version of openrouteservice, change the tag (after the colon) in the last line. + +[//]: # (TODO: adjust to latest docker setup) + +```shell +# create directories for volumes to mount as local user +mkdir -p docker/conf docker/elevation_cache docker/graphs docker/logs/ors docker/logs/tomcat +docker run -dt -u "${UID}:${GID}" \ + --name ors-app \ + -p 8080:8080 \ + -v $PWD/docker/graphs:/home/ors/ors-core/data/graphs \ + -v $PWD/docker/elevation_cache:/home/ors/ors-core/data/elevation_cache \ + -v $PWD/docker/logs/ors:/home/ors/ors-core/logs/ors \ + -v $PWD/docker/logs/tomcat:/home/ors/tomcat/logs \ + -v $PWD/docker/conf:/home/ors/ors-conf \ + -v $PWD/docker/data:/home/ors/ors-core/data \ + #-e "BUILD_GRAPHS=True" \ + -e "JAVA_OPTS=-Djava.awt.headless=true -server -XX:TargetSurvivorRatio=75 -XX:SurvivorRatio=64 -XX:MaxTenuringThreshold=3 -XX:+UseG1GC -XX:+ScavengeBeforeFullGC -XX:ParallelGCThreads=4 -Xms1g -Xmx2g" \ + -e "CATALINA_OPTS=-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9001 -Dcom.sun.management.jmxremote.rmi.port=9001 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=localhost" \ + openrouteservice/openrouteservice:latest +``` + +## Configure + +[//]: # (TODO: review below here after docker setup merge) + + +Running openrouteservice out of the box via Docker and docker-compose is a great way to quickly get into how to use +openrouteservice. For most applications though, you would want to customise some things such as which profiles you want +to build and the data that you want to route with. In its initial Docker container form, openrouteservice uses an older +test dataset of Heidelberg (Germany) as the base data, and only builds the car profile. To do more than that, you need +to get your hands a little dirty with some configuration settings. This may sound a little daunting, but it is designed +in a way that once you overcome the initial understanding of the configuration and Docker, you will be able to use your +own datasets and decide which profiles to use in no time. + +### What you get + +All the above scenarios will: + +1. Pull the openrouteservice Docker image from Docker Hub and start a container named `ors-app` +2. Launch the openrouteservice service on port `8080` within a tomcat running in that container, available at the + address `http://localhost:8080/ors`. +3. Create a local `./docker` folder containing the files used and produced by openrouteservice for easy access. Most + relevant is `./docker/conf/ors-config.yml` controlling ORS behaviour, and the test OSM data + file `/home/ors/ors-core/data/osm_file.pbf` of Heidelberg and surroundings. + +### Customization + +Once you have a built image you can decide to start a container with different settings, e.g. changing the active +profiles or other settings. To run ORS with a custom configuration, modify the `./docker/conf/ors-config.yml` to your +needs, and restart the container. You can obviously also modify the volume mappings in the `docker-compose.yml` to your +needs. **Note that using `docker-compose restart` does not carry across changes made inside the `docker-compose.yml` +file, so you should use `docker-compose down` to take down the container, and then `docker-compose up` to restart it +again when you have made changes.** + +For detailed information on the settings you can make, see the chapter +on [configuration](/run-instance/configuration/index.md). + +Old ORS configuration files in JSON format are **deprecated**. If you have a custom `ors-config.json` file from a +previous installation we strongly recommend to migrate to the new YAML format. For the transitional period ORS allows +the use of old format JSON files placed at `./docker/conf/ors-config.json`. All settings in such a file, if present, +will override settings in the proper YAML format. + +If you are making changes to anything relating to the OSM data or the settings that change how graphs are built, you +need to delete the folders in `graphs` or set the environment variable `BUILD_GRAPHS=True` (see comment in Dockerfile or +examples above). This makes it so that the graphs are built again with the new data/settings. + +### Different OSM file + +To change the OSM data that is used, you can either overwrite the `docker/data/osm_file.pbf` file, or modify the volume +mount of `/home/ors/ors-core/data` to a directory containing a file `osm_file.pbf`, or volume mount something +like `/YOUR/PATH/TO/ANOTHER/OSM_FILE.pbf:/home/ors/ors-core/data/osm_file.pbf`. + +Make sure to set the environment variable `BUILD_GRAPHS=True` or empty the `docker/graphs/` directory before restarting +the container. + +If you are building the Docker image locally, you can also point the build argument `OSM_FILE` to your desired OSM file +before building the image. + +Note, `.osm`, `.osm.gz`, `.osm.zip` and `.pbf` file format are supported as OSM files. + +If your dataset is very large, it may be necessary to adjust the `-Xmx` parameter of `JAVA_OPTS` environment variable. A +good rule of thumb is to give Java 2 x file size of the PBF **per profile**. + +::: details Further info on memory settings +In the `JAVA_OPTS` line of the `docker-compose.yml` file, you will see the `-Xms1g` and `-Xmx2g` items. These tell Java +that it should start with 1GB RAM assigned to it, and go no higher than 2 GB of usage. If let's say your pbf file is 1.5 +GB in size, and you have two profiles configured (e.g. car and foot-walking), then you would update the `-Xmx` item to +be **AT LEAST** `-Xmx6g` (1.5GB * 2 Profiles * 2). In general, we would recommend adding a bit more to the RAM value if +possible to reduce the chances of hitting an out of memory exception towards the end of the graph building. +::: + +### UID + +If you need to change the UID the ors is running with, you can use these variables: + +```bash +# set it explicitly to 1001 +ORS_UID=1001 ORS_GID=1001 docker compose up -d + +# or set it to the current user +ORS_UID=${UID} ORS_GID=${GID} docker compose up -d +``` + +### Volumes + +There are some important directories one might want to preserve on the host machine, to survive container regeneration. +These directories should be mapped as volumes. + +- `/home/ors/ors-core/data/graphs`: Contains the built graphs after ORS initialized. +- `/home/ors/ors-core/data/elevation_cache`: Contains the CGIAR elevation tiles if elevation was specified. +- `/home/ors/ors-core/logs/ors`: Contains the ORS logs. +- `/home/ors/tomcat/logs`: Contains the Tomcat logs. +- `/home/ors/ors-conf`: Contains the `ors-config.json` which is used to control ORS. +- `/home/ors/ors-core/data`: Contains the OSM file `osm_file.pbf` being used to generate graphs. + +Look at the [`docker-compose.yml`](https://github.com/GIScience/openrouteservice/blob/main/docker-compose.yml) for +examples. + +### Environment variables + +- `BUILD_GRAPHS`: Forces ORS to rebuild the routing graph(s) when set to `True`. Useful when another PBF is specified in + the Docker volume mapping to `/home/ors/ors-core/data/osm_file.pbf` +- `JAVA_OPTS`: Custom Java runtime options, such as `-Xms` or `-Xmx` +- `CATALINA_OPTS`: Custom Catalina options + +Specify either during container startup or in `docker-compose.yml`. + +### Build arguments + +When building the image, the following arguments are customizable: + +- `ORS_CONFIG`: Can be changed to specify the location of a custom `ors-config.json` file. + Default `./ors-api/src/main/resources/ors-config.json`. +- `OSM_FILE`: Can be changed to point to a local custom OSM file. Default `./ors-api/src/test/files/heidelberg.osm.gz`. + +## Instance infrastructure + +Though having a single container works great for smaller datasets or when the graph data doesn't need updating, in many +real world implementations having just the one instance isn't the most suitable solution. If you have one container, +then all building and serving of routes happens through that single container, meaning that when you rebuild graphs, you +can't make any requests to that instance for things like directions as there are no complete graphs that can be used to +generate routes with. If it is important that you have graph updates from new data whilst ensuring that there is a +minimal amount of time during which users cannot make requests, we would recommend having two instances - one that is +permanently active for serving requests, and one that gets fired up to rebuild graphs. + +In that setup, when graphs have been built you can simply stop the container serving requests, replace the graphs used ( +they are mapped to a folder on the host machine which is defined in the `docker-compose` file), and then restart the +container. The new graphs will be reloaded into memory (the amount of time needed for this depends on the size of the +graphs and the type of hard drive) and then ready to use for routing. The downtime from reloading already built graphs +is normally far less than the time needed to build the graphs. A thing to note though is that you should ensure that the +config files and the amount of RAM allocated (as described earlier) is the same on both the builder and the request +server else the newly built graphs may not load. **Also, ensure that `BUILD_GRAPHS` parameter in the `docker-compose` +file used by the request serving container is set to false else it will try to build the graphs for itself!** diff --git a/docs/run-instance/system-requirements.md b/docs/run-instance/system-requirements.md index 0948f39ec2..b2972b3311 100644 --- a/docs/run-instance/system-requirements.md +++ b/docs/run-instance/system-requirements.md @@ -13,6 +13,16 @@ As a guide, you can look at the size of OSM data extracts as a rough guide as to [//]: # (TODO: @koebi was working on a set of example memory footprint values or something similar? Add here) +## JVM configuration + +Independent of the configuration of the openrouteservice itself, you might need to adjust settings of the Java Virtual Machine (JVM) running the code. Since the memory requirements of openrouteservice are proportional to the size of the OSM data (and therefore the resulting graph), the setting that needs to be adjusted most often is the heap memory size. + +[//]: # (TODO: elaborate) + +``` +JAVA_OPTS="-Xms105g -Xmx105g " +``` + ## Memory mapping in large builds with a containerized openrouteservice instance If you are running a large build (e.g. a planet file) then you may need to increase the number of memory mappings. You only need to do this on the host machine as this value is used by the Docker containers running on it as well. To do this, go into the system configuration file with `sudo nano /etc/sysctl.conf` and add the following line to the bottom of the file: @@ -28,3 +38,4 @@ The usual sign that you need to do this change is if you see something similar t # An error report file with more information is saved as: # /ors-core/hs_err_pid128.log ``` + diff --git a/docs/run-instance/war-docker/build.md b/docs/run-instance/war-docker/build.md deleted file mode 100644 index 666004c3de..0000000000 --- a/docs/run-instance/war-docker/build.md +++ /dev/null @@ -1,7 +0,0 @@ -# Build Docker Image with openrouteservice WAR - -::: tip Hint -If you don't need changes in the code, you don't need to build the artifact yourself. If this is the case, skip this page and go to [download](download.md). -::: - -... \ No newline at end of file diff --git a/docs/run-instance/war-docker/configure.md b/docs/run-instance/war-docker/configure.md deleted file mode 100644 index b941eb3896..0000000000 --- a/docs/run-instance/war-docker/configure.md +++ /dev/null @@ -1 +0,0 @@ -# Configure Docker Image with openrouteservice WAR \ No newline at end of file diff --git a/docs/run-instance/war-docker/download.md b/docs/run-instance/war-docker/download.md deleted file mode 100644 index cbc806a0b0..0000000000 --- a/docs/run-instance/war-docker/download.md +++ /dev/null @@ -1 +0,0 @@ -# Download Docker Image with openrouteservice WAR \ No newline at end of file diff --git a/docs/run-instance/war-docker/index.md b/docs/run-instance/war-docker/index.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/run-instance/war-docker/run.md b/docs/run-instance/war-docker/run.md deleted file mode 100644 index 71487a39f5..0000000000 --- a/docs/run-instance/war-docker/run.md +++ /dev/null @@ -1 +0,0 @@ -# Run Docker Image with openrouteservice WAR \ No newline at end of file diff --git a/docs/run-instance/war-docker/troubleshoot.md b/docs/run-instance/war-docker/troubleshoot.md deleted file mode 100644 index 9a7f043284..0000000000 --- a/docs/run-instance/war-docker/troubleshoot.md +++ /dev/null @@ -1 +0,0 @@ -# Troubleshoot Docker Image with openrouteservice WAR \ No newline at end of file diff --git a/docs/run-instance/war/build.md b/docs/run-instance/war/build.md deleted file mode 100644 index fbb5d76b6e..0000000000 --- a/docs/run-instance/war/build.md +++ /dev/null @@ -1,23 +0,0 @@ -# Build openrouteservice WAR - - -::: tip Hint -If you don't need changes in the code, you don't need to build the artifact yourself. If this is the case, skip this page and go to [download](download.md). -::: - -First checkout the openrouteservice repository and setup your local project. -How this is done is independent of the artifact type you want to use and is documented in [Building from Source](/run-instance/building-from-source.md). -There you will also learn how to carry out tests, which is essential for code changes. - -When your project is set up, you can generate a deployable openrouteservice WAR: -```shell -mvn clean package -PbuildWar -``` - -You will find the WAR file here: - -```shell -ors-api/target/ors.war -``` - -Read in the next chapters how to configure and run/deploy the war. diff --git a/docs/run-instance/war/configure.md b/docs/run-instance/war/configure.md deleted file mode 100644 index 508103035e..0000000000 --- a/docs/run-instance/war/configure.md +++ /dev/null @@ -1 +0,0 @@ -# Configure openrouteservice WAR diff --git a/docs/run-instance/war/download.md b/docs/run-instance/war/download.md deleted file mode 100644 index f1b4c0c504..0000000000 --- a/docs/run-instance/war/download.md +++ /dev/null @@ -1,4 +0,0 @@ -# Download openrouteservice WAR - -Starting with version 8 you can download the ready to use WAR from the "Assets" section of the desired release -from our github [releases](https://github.com/GIScience/openrouteservice/releases) page. diff --git a/docs/run-instance/war/index.md b/docs/run-instance/war/index.md deleted file mode 100644 index da926445dc..0000000000 --- a/docs/run-instance/war/index.md +++ /dev/null @@ -1,4 +0,0 @@ -# Run openrouteservice as WAR - -Like older versions, ORS version 8 can still be built and run as a Web Application Resource aka Web ARchive (WAR). -A WAR can be deployed to a Servlet Container like Tomcat, which is running as a service. diff --git a/docs/run-instance/war/run.md b/docs/run-instance/war/run.md deleted file mode 100644 index d6125bfad7..0000000000 --- a/docs/run-instance/war/run.md +++ /dev/null @@ -1,23 +0,0 @@ -# Run openrouteservice WAR - -Running a WAR means deploying it to a Tomcat instance: - -1. Install Tomcat 10 on your system. E.g. on Ubuntu 22.04, follow these [instructions](https://linuxize.com/post/how-to-install-tomcat-10-on-ubuntu-22-04/). - -2. If you want to use system settings (i.e. Java heap size) other than the default, then you need to add these to the `setenv.sh` file in your tomcat bin folder, typically somewhere like `/usr/share/tomcat10/bin/`. If the file is not present, then you can create it. - - The environment variable `ORS_CONFIG_LOCATION` and other optional environment variables need to be written to that file, too. The settings generally used on our servers are similar to: - - ```shell - 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)" - ORS_CONFIG_LOCATION=/path/to/ors-config.yml - ``` - -3. If you add these new settings to the `setenv.sh` file, then you need to restart Tomcat for these to take effect using a command like `sudo systemctl restart tomcat.service`. - -4. To get openrouteservice up and running, copy the `ors.war` file to the Tomcat webapps folder. - -5. 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: ready` message, you are good to go in creating routes. - -6. Your configuration file and all input / output files and directories referenced by that configuration need to be accessible (and in case of the output folders, writable) to the user your Tomcat instance is running as. You might need to adjust the location of said files and folders or `chmod` / `chown` them accordingly. diff --git a/docs/run-instance/war/troubleshoot.md b/docs/run-instance/war/troubleshoot.md deleted file mode 100644 index b9efa23a9c..0000000000 --- a/docs/run-instance/war/troubleshoot.md +++ /dev/null @@ -1 +0,0 @@ -# Troubleshoot openrouteservice WAR \ No newline at end of file