GIScience · jhaeu · Mar 19, 2024 · Mar 11, 2024 · Mar 12, 2024 · Mar 12, 2024
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -80,7 +80,8 @@ RELEASING:
 - unify edge splitting across isochrone builders, and split edges based on coordinates rather than their actual distance in meters ([#1708](https://github.com/GIScience/openrouteservice/pull/1708))
 - add missing encoder_options to the documentation [#1752](https://github.com/GIScience/openrouteservice/pull/1752)
 - add config tests for json config [#1749](https://github.com/GIScience/openrouteservice/pull/1749)
-
+- adapted documentation to new docker setup ([#1746](https://github.com/GIScience/openrouteservice/pull/1746))
+
 ### Deprecated
 - JSON configuration and related classes ([#1506](https://github.com/GIScience/openrouteservice/pull/1506))
 

diff --git a/README.md b/README.md
@@ -9,83 +9,110 @@
 [![Release](https://img.shields.io/github/v/release/GIScience/openrouteservice)](https://github.com/GIScience/openrouteservice/releases/latest)
 [![LICENSE](https://img.shields.io/github/license/GIScience/openrouteservice)](LICENSE)
 
-The **openrouteservice API** provides global spatial services by consuming user-generated and collaboratively collected free geographic data directly from [OpenStreetMap](http://www.openstreetmap.org). It is highly customizable, performant and written in Java.
+Openrouteservice is a highly customizable, performant routing service written in Java. 
+It uses a [forked and edited version of graphhopper 4.0](https://github.com/GIScience/graphhopper) 
+and provides global spatial services by consuming user-generated and collaboratively collected free geographic data directly from [OpenStreetMap](http://www.openstreetmap.org): 
 
-The following services are available via an HTTP interface served by Tomcat.
-- **Directions** - Returns a route between two or more locations for a selected profile with customizable additional settings and instructions.
-- **Isochrones** - Obtains areas of reachability from given locations.
-- **Matrix** - Computes one-to-many, many-to-one or many-to-many routes for any mode of transport provided by openrouteservice.
+* [Directions Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/directions/): Get directions for different modes of transport
+* [Isochrones Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/isochrones/): Obtain areas of reachability from given locations
+* [Matrix Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/matrix/): Obtain one-to-many, many-to-one and many-to-many matrices for time and distance
+* [Snapping Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/snapping/)¹: Snap coordinates to the graph edges  
+* [Export Service](https://giscience.github.io/openrouteservice/api-reference/endpoints/export/)¹: Export the base graph for different modes of transport
+* [Health Endpoint](https://giscience.github.io/openrouteservice/api-reference/endpoints/health/)¹: Get information on the health of the running openrouteservice instance
+* [Status Endpoint](https://giscience.github.io/openrouteservice/api-reference/endpoints/status/)¹: Get information on the status of the openrouteservice instance
 
-To play around with openrouteservice you may use our [demonstration server](https://maps.openrouteservice.org) which comes with both the backend and a [frontend](https://github.com/GIScience/ors-map-client). Or simply [sign up](https://openrouteservice.org/dev/#/signup) for an API key and fire your requests against the API directly.
+¹) **Snapping, Export, Health and Status Endpoint are not available in our public openrouteservice API aka "live API"!** 
+You can use them by running your own instance of openrouteservice.
 
-Please note that openrouteservice uses a forked and edited version of [graphhopper 4.0](https://github.com/GIScience/graphhopper) which can be found [here](https://github.com/GIScience/graphhopper).
+And to avoid any misunderstandings, it should also be mentioned at this point that our live API provides several other endpoints 
+that are **not part of openrouteservice software/repository**:
 
-[![ors client accessibility](https://user-images.githubusercontent.com/23240110/30385487-9eac96b8-98a7-11e7-9357-afd4df8fccdf.png)](https://openrouteservice.org/reach)
+* [openpoiservice](https://github.com/GIScience/openpoiservice): A stand-alone service from HeiGIT that returns points of interest in the area surrounding a geometry
+* [openelevationservice](https://github.com/GIScience/openelevationservice): A stand-alone service from HeiGIT that returns the elevation for point or line geometries
+* [Pelias](https://www.pelias.io): A (reverse) geocoder hosted by HeiGIT that resolves geographic coordinates to addresses and vice versa
+* [VROOM](https://github.com/VROOM-Project/vroom): The Vehicle Routing Open-source Optimization Machine hosted by HeiGIT 
 
-**Note**
+To play around with openrouteservice you may use our [demonstration server](https://maps.openrouteservice.org) which comes with both the backend and a [frontend](https://github.com/GIScience/ors-map-client). 
+Or simply [sign up](https://openrouteservice.org/dev/#/signup) for an API key and fire your requests against the API directly.
+You can also do this in our [API Playground](https://openrouteservice.org/dev/#/api-docs) - take a look at the [API Reference](https://giscience.github.io/openrouteservice/api-reference/) to get more information.
 
-- Our geocoding API is a separate service running the stack built around [**Pelias**](https://github.com/pelias/pelias).
-- Our locations/API is another service which we have coined **openpoiservice** which can be found [here](https://github.com/GIScience/openpoiservice).
+![map-client-isochrones](docs/public/map-client-isochrones.png)
 
 
-## Changelog/latest changes
-
-[Openrouteservice CHANGELOG](https://github.com/GIScience/openrouteservice/blob/main/CHANGELOG.md)
-
-## Contribute
+## Installation
 
-We appreciate any kind of contribution - bug reports, new feature suggestion or improving our translations are greatly appreciated. Feel free to create an [issue](https://github.com/GIScience/openrouteservice/issues) and label it accordingly. If your issue regards the openrouteservice web-app please use the [corresponding repository](https://github.com/GIScience/ors-map-client/issues).
+You can easily [run openrouteservice](https://giscience.github.io/openrouteservice/run-instance/) yourself! 
 
-If you want to contribute your improvements, please follow the steps outlined in [our CONTRIBUTION guidelines](./CONTRIBUTE.md)
+**tl;dr:** We suggest [using docker](https://giscience.github.io/openrouteservice/run-instance/running-with-docker) to install and launch openrouteservice. 
+In short, a machine with a working [docker installation](https://www.digitalocean.com/community/tutorial_collections/how-to-install-and-use-docker) will get everything done for you. 
 
-The [sourcespy dashboard](https://sourcespy.com/github/giscienceopenrouteservice/) provides a high level overview of the repository including technology summary, module dependencies and other components of the system.
+Change to the directory where you want to install your local openrouteservice and first create some directories, where openrouteservice will persist its data:
+```shell
+mkdir -p ors-docker/config ors-docker/elevation_cache ors-docker/graphs ors-docker/files ors-docker/logs
+```
 
-## Installation
+Only use nightly (main branch) if you know what you do. 
+We recommend running docker compose with the latest release version. 
+Get the docker compose file for a release, e.g. v8.0.0: 
+```shell
+wget https://github.com/GIScience/openrouteservice/releases/download/v8.0.0/docker-compose.yml
+```
 
-We suggest using docker to install and launch openrouteservice backend. In short, a machine with a working [docker installation](https://www.digitalocean.com/community/tutorial_collections/how-to-install-and-use-docker) will get everything done for you. 
-
-Only use nightly (main branch) if you know what you do. We recommend running docker compose with the latest release version:
-
-```bash
-# For example for the latest release
-git clone https://github.com/GIScience/openrouteservice.git
-cd openrouteservice
-# Checkout latest version
-export LATEST_ORS_RELEASE=$(git describe --tags --abbrev=0); 
-git checkout $LATEST_ORS_RELEASE
-# If the docker folder exists cd into it
-cd docker || echo "No docker folder found. Continue with next step."
-# Now change the version the docker-compose.yml uses
-sed -i='' "s/openrouteservice\/openrouteservice:nightly/openrouteservice\/openrouteservice:$LATEST_ORS_RELEASE/g" docker-compose.yml
-sed -i='' "s/openrouteservice\/openrouteservice:latest/openrouteservice\/openrouteservice:$LATEST_ORS_RELEASE/g" docker-compose.yml
-# Run docker compose with
+Start openrouteservice in the background:
+```shell
 docker compose up -d
 ```
 
-For more details, check the [docker installation guide](https://giscience.github.io/openrouteservice/run-instance/running-with-docker).
+This will pull the openrouteservice docker image of the selected version and start it up using an example setup
+and the provided test OSM file for Heidelberg/Germany and surrounding area.
 
-For instructions on how to [build from source](https://giscience.github.io/openrouteservice/run-instance/installation/building-from-source) or [configure](https://giscience.github.io/openrouteservice/openrouteservice/run-instance/configuration/), visit our [Installation Instructions](https://giscience.github.io/openrouteservice/openrouteservice/run-instance/installation/).
+To see the container's logs, run:
+```shell
+docker compose logs 
+```
+
+Stop the container with:
+```shell
+docker compose down
+```
 
 ## Usage
 
-Openrouteservice offers a set of endpoints for different spatial purposes. By default, they will be available at
+The above mentioned endpoints will be available on port 8080:
 
 - `http://localhost:8080/ors/v2/directions`
 - `http://localhost:8080/ors/v2/isochrones`
 - `http://localhost:8080/ors/v2/matrix`
+- `http://localhost:8080/ors/v2/snap`
+- `http://localhost:8080/ors/v2/export`
+- `http://localhost:8080/ors/v2/health`
+- `http://localhost:8080/ors/v2/status`
 
-You can find more information in the [Installation Instructions](https://giscience.github.io/openrouteservice/run-instance/running-with-docker).
+You can find more information in the endpoint documentation pages linked above.
 
-## API Documentation
+On the [API Reference](https://giscience.github.io/openrouteservice/api-reference/) there is also a description
+how you can use the Swagger-UI and the API Playground for local instances of openrouteservice.
 
-For an easy and interactive way to test the api, visit our [API Playground](https://openrouteservice.org/dev/#/api-docs).
-After obtaining your key you can try out the different endpoints instantly and start firing requests.
+
+## Changelog/latest changes
+
+[Openrouteservice CHANGELOG](https://github.com/GIScience/openrouteservice/blob/main/CHANGELOG.md)
+
+
+## Contribute
+
+We appreciate any kind of contribution - bug reports, new feature suggestion or improving our translations are greatly appreciated. Feel free to create an [issue](https://github.com/GIScience/openrouteservice/issues) and label it accordingly. If your issue regards the openrouteservice web-app please use the [corresponding repository](https://github.com/GIScience/ors-map-client/issues).
+
+If you want to contribute your improvements, please follow the steps outlined in [our CONTRIBUTION guidelines](./CONTRIBUTE.md)
+
+The [sourcespy dashboard](https://sourcespy.com/github/giscienceopenrouteservice/) provides a high level overview of the repository including technology summary, module dependencies and other components of the system.
 
 
 ## Questions
 
 For questions please use our [community forum](https://ask.openrouteservice.org).
 
+
 ## Translations
 
 If you notice anything wrong with translations, or you want to add a new language to the ORS instructions, we have some instructions in our [backend documentation](https://GIScience.github.io/openrouteservice/contributing/contributing-translations) about how you can submit an update. You can also look over at our [maps client GitHub](https://github.com/GIScience/ors-map-client/#add-language) if you want to contribute the language to there as well (adding or editing the language in the openrouteservice GitHub repo only affects the instructions - any new language also needs adding to the client).
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -16,7 +16,7 @@ services:
     image: local/openrouteservice:latest
     # Advanced option! If you different ids to 0:0 and 1000:1000, you have to rebuild the container with the build args UID,GID.
     # The user command is useful if you want easier bind mount access or better security.
-    #user: "1000:1000" # Run "mkdir -p ors && sudo chown -R 1000:1000 ors" before starting the container!
+    #user: "1000:1000" # Run "mkdir -p ors-docker/config ors-docker/elevation_cache ors-docker/files ors-docker/graphs ors-docker/logs && sudo chown -R 1000:1000 ors" before starting the container!
     volumes:  # Mount relative directories. ONLY for local container runtime. To switch to docker managed volumes see 'Docker Volumes configuration' section below.
       - ./ors-docker:/home/ors  # Mount the ORS application directory (for logs, graphs, elevation_cache, etc.) into its own directory
       #- ./graphs:/home/ors/graphs  # Mount graphs directory individually

diff --git a/docs/index.md b/docs/index.md
@@ -22,7 +22,7 @@ features:
     - title: Installation
       details: Set up your own openrouteservice instance.
       linkText: Instructions
-      link: /run-instance/installation/
+      link: /run-instance/
     - title: Data Sources
       details: Find all information on the data used by the openrouteservice here.
       linkText: Data

diff --git a/docs/public/map-client-isochrones.png b/docs/public/map-client-isochrones.png
diff --git a/docs/run-instance/building-from-source.md b/docs/run-instance/building-from-source.md
@@ -1,6 +1,8 @@
 # Building from Source
 
-If you need to customize your openrouteservice instance even further than what is possible by [configuration](/run-instance/configuration/index.md), or want to start [contributing](/contributing/index.md) to the openrouteservice project, the following section will give you starting points.
+If you need to customize your openrouteservice instance even further than what is possible by [configuration](/run-instance/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/index.md)! The following instructions are useful to get you set up to start modifying the code.
+
 
 ## Prerequisites
 
@@ -22,36 +24,6 @@ This creates a directory named `openrouteservice` containing the downloaded sour
 
 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  
@@ -65,11 +37,6 @@ and a small OSM data set from Heidelberg.
 
 In the [Configuration](configuration/index.md) section you find the options how you can use customised configurations.  
 
-## 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/index.md)! 
-
-The following instructions are useful to get you set up to start modifying the code.
 
 ### Running from within IDE
 
@@ -216,3 +183,81 @@ If you need to make adjustments to our forked and edited [GraphHopper repository
 4. Test your new functionality and run all tests after rebasing your feature branch with the latest `main` branch. Adjust tests if necessary.
 
 5. If successful, create a PR for both [openrouteservice](https://github.com/GIScience/openrouteservice/pulls) and [GraphHopper](https://github.com/GIScience/graphhopper/pulls) against `master` and `ors_4.0` branches, respectively.
+
+
+## Build runnable artifacts
+
+### 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.
+
+
+### Build docker image
+
+::: tip
+This chapter only describes how to _build_ a docker container locally.
+Before you _run_ your custom docker image the first time, 
+please read [running prebuilt images](running-with-docker.md#running-prebuilt-images) 
+to learn the preconditions and how the dockerized openrouteservice is operated.
+:::
+
+To build a local openrouteservice docker image based on the local (modified) code, 
+it is convenient to use the docker compose file in the project directory. 
+When you are in the project directory and run the first time 
+
+```shell
+docker compose up 
+```
+
+your local docker image `local/openrouteservice:latest` will be built. If it already exists, the existing image will be used.
+
+To rebuild the image with docker compose, you can execute 
+
+```shell
+docker compose build 
+```
+
+or, of course, you can also use docker directly to build your image:
+
+```shell
+docker build . -t local/openrouteservice
+```
+
+When building the docker image locally, under the hood `mvn clean package` will be executed, 
+which compiles you local source code to a fat jar that will be placed in your docker image.
+
+If you don't want to build locally but instead run the nightly image,
+modify the `docker-compose.yml`:
+
+```yaml
+image: local/openrouteservice:latest // [!code --]
+image: openrouteservice/openrouteservice:nightly // [!code ++]
+```
+
diff --git a/docs/run-instance/configuration/index.md b/docs/run-instance/configuration/index.md
@@ -14,8 +14,6 @@ There are two (optional) ways for you to provide openrouteservice the location o
       ```
 If both are specified, the program argument wins. 
 
-[//]: # (TODO: test this)
-
 If no config location is specified, openrouteservice will look for a configuration file `ors-config.yml` in the locations below in that order.
 The first existing file is used as configuration.
 
@@ -25,8 +23,6 @@ The first existing file is used as configuration.
 | `~/.config/openrouteservice/ors-config.yml` | User configuration directory                |
 | `/etc/openrouteservice/ors-config.yml`      | Global configuration directory              |
 
-[//]: # (TODO: test this)
-
 ::: tip
 At program start openrouteservice reports which configuration file was loaded.
 :::