From 0e107ed8a6c34fc63d9efbbf5ccca309c26830de Mon Sep 17 00:00:00 2001 From: Jochen Haeussler Date: Fri, 16 Feb 2024 19:19:43 +0100 Subject: [PATCH] docs(run-instance): migrated content to new structure also added and updated things on the fly --- docs/.vitepress/config.js | 70 ++++++++-------- docs/contributing/index.md | 2 +- .../opening-project-in-intellij.md | 9 --- docs/getting-started.md | 2 +- .../building-from-source.md | 64 ++++++++++----- docs/run-instance/configuration/index.md | 80 ++++++++++++++----- docs/run-instance/configuration/json.md | 7 +- .../configuration/migrate-from-json.md | 3 + docs/run-instance/data.md | 50 ++++++++++-- docs/run-instance/index.md | 72 +++++------------ docs/run-instance/installation/index.md | 9 --- .../installation/running-jar-war.md | 46 ----------- docs/run-instance/jar-docker/build.md | 7 +- docs/run-instance/jar-docker/configure.md | 11 ++- docs/run-instance/jar-docker/index.md | 4 + docs/run-instance/jar-docker/run.md | 20 ++++- docs/run-instance/jar/build.md | 29 ++++++- docs/run-instance/jar/index.md | 5 ++ docs/run-instance/war-docker/build.md | 8 +- docs/run-instance/war-docker/index.md | 0 docs/run-instance/war/build.md | 24 +++++- docs/run-instance/war/configure.md | 2 +- docs/run-instance/war/download.md | 5 +- docs/run-instance/war/index.md | 4 + docs/run-instance/war/run.md | 24 +++++- 25 files changed, 348 insertions(+), 209 deletions(-) delete mode 100644 docs/contributing/opening-project-in-intellij.md rename docs/run-instance/{installation => }/building-from-source.md (61%) create mode 100644 docs/run-instance/configuration/migrate-from-json.md delete mode 100644 docs/run-instance/installation/index.md delete mode 100644 docs/run-instance/installation/running-jar-war.md create mode 100644 docs/run-instance/jar-docker/index.md create mode 100644 docs/run-instance/jar/index.md create mode 100644 docs/run-instance/war-docker/index.md create mode 100644 docs/run-instance/war/index.md diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 40f14057bb..901c43b5db 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -96,13 +96,39 @@ export default defineConfig({ items: [ {text: 'System Requirements', link: '/run-instance/system-requirements'}, {text: 'Data', link: '/run-instance/data'}, - { - text: 'Installation', collapsed: true, link: '/run-instance/installation/', + {text: 'ORS as JAR', collapsed: true, link: '/run-instance/jar/index.md', items: [ - {text: 'Running with Docker', link: '/run-instance/installation/running-with-docker'}, - {text: 'Running JAR / WAR', link: '/run-instance/installation/running-jar-war'}, - {text: 'Building from Source', link: '/run-instance/installation/building-from-source'}, - ] + {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: 'Configuration', collapsed: true, link: '/run-instance/configuration/', @@ -137,38 +163,6 @@ export default defineConfig({ {text: 'JSON config (deprecated)', link:'/run-instance/configuration/json.md'} ] }, - {text: 'As WAR', collapsed: true, - 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: 'As JAR', collapsed: true, - 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: 'As Docker Container (WAR)', collapsed: true, - 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: 'As Docker Container (JAR)', collapsed: true, - 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'} - ]}, ] }, { diff --git a/docs/contributing/index.md b/docs/contributing/index.md index d27bfc6333..05e7c671b1 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -16,7 +16,7 @@ please use the [corresponding repository](https://github.com/GIScience/ors-maps- ## Contributing code -To help you get started, here is a document describing how to [open the code in IntelliJ](opening-project-in-intellij). +To help you get started, here is a document describing how to [build openrouteservice from code](/run-instance/building-from-source.md). We also put together a few [guidelines](https://github.com/GIScience/openrouteservice/blob/main/CONTRIBUTE.md) to help you in the process and keep the repository clean and tidy. diff --git a/docs/contributing/opening-project-in-intellij.md b/docs/contributing/opening-project-in-intellij.md deleted file mode 100644 index 2a763abc37..0000000000 --- a/docs/contributing/opening-project-in-intellij.md +++ /dev/null @@ -1,9 +0,0 @@ -# Opening openrouteservice code in IntelliJ - -Though IntelliJ provides functionality to directly clone a repository, the steps below are the general procedure for getting openrouteservice up and running in IntelliJ: -1. Clone the repository into a folder -2. Open IntelliJ and Create a project via File -> New -> Project from Existing Sources -3. Select the "pom.xml" file from the cloned "openrouteservice" folder and click "Open" -4. Click through project settings with "Next" until you reach the page for selecting project SDK. -5. Choose "17" as project SDK and click "Next" -6. Finalize the project import by clicking "Finish" in the last window. diff --git a/docs/getting-started.md b/docs/getting-started.md index 6425f0eeeb..2ee40cdcc1 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/installation/building-from-source) + * [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) * [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/installation/building-from-source.md b/docs/run-instance/building-from-source.md similarity index 61% rename from docs/run-instance/installation/building-from-source.md rename to docs/run-instance/building-from-source.md index bce60cae23..91015a6008 100644 --- a/docs/run-instance/installation/building-from-source.md +++ b/docs/run-instance/building-from-source.md @@ -1,6 +1,6 @@ # 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 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), or want to start [contributing](/contributing/index.md) to the openrouteservice project, the following section will give you starting points. ## Prerequisites @@ -9,42 +9,70 @@ The following documentation assumes you are running an Ubuntu 20.04 system (also * [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 -## Installation from source +## Get Source Code -To build openrouteservice from source, you can use the following commands: +Clone and switch into the repository with the following commands: ```shell git clone https://github.com/user/openrouteservice.git cd openrouteservice -mvn package ``` -If you have made modifications to the code, you should run all tests before building and using openrouteservice. For a significant part of the tests you need to activate a maven profile called `apitests` to run them. Use the following commands: +## Running with maven + +You should be able to run the application directly with ```shell -mvn -Papitests verify -# afterwards you can build the artefacts without running the tests again by issuing the following command: -mvn -DskipTests package +mvn spring-boot:run ``` -[//]: # (TODO: overhaul contents below after integrating the jar build PR) -After running this command, you will find the artefact at `ors-api/target/ors.war`. +or in your IDE (see below). This will start openrouteservice on port `8082` with the default configuration `ors-config.yml` in the project root directory +and a small OSM data set from Heidelberg. + +In [Configuration](configuration/index.md) you find the options how you can use customised configurations. -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 10. In both cases the requirements of configuration and source files discussed [here](running-jar-war) apply. +To create a deployable WAR or JAR artifact, please refer to the documentation for [JAR](jar/build.md) and [WAR](war/build.md). -[//]: # (TODO: the part below partly belongs somewhere in the contributing section; running with IDE needs to be overhauled, too, since it does not mention running with spring boot run config) ## Running from within IDE To run the project from within your IDE, you have to: - 1. Set up your IDE project and import `openrouteservice` - modules as Maven model. - For IntelliJ Idea, have a look at [these instructions](/contributing/opening-project-in-intellij.md). +1. Open IntelliJ and Create a project via File -> New -> Project from Existing Sources +2. Select the "pom.xml" file from the cloned "openrouteservice" folder and click "Open" +3. Click through project settings with "Next" until you reach the page for selecting project SDK. +4. Choose "17" as project SDK and click "Next" +5. Finalize the project import by clicking "Finish" in the last window. +6. Configure your IDE to run `spring-boot:run` as the maven goal. Now you can run your application directly in IntelliJ. +7. To use a different config file than ors-config.yml in the project directory, you can set the environment variable `ORS_CONFIG_LOCATION=` in your run config. +7. You can run all tests via JUnit. + + +## Running Tests - 2. Configure your IDE to run `spring-boot:run` as the maven goal, setting the - environment variable `ORS_CONFIG_LOCATION=ors-config.yml`. +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. + +It is very convenient to run unit tests (all or just one or some) in the IDE. +You can also run tests with maven on the command line. Here are some examples, checkout the maven documentation for more options. + +```shell +mvn clean test # runs unit tests in all modules +mvn clean test -pl :ors-api # runs unit tests in ors-api +mvn clean test -pl :ors-api -Dtest="APIEnumsTest" # run tests in a single test class +mvn clean test -pl :ors-api -Dtest="APIEnumsTest#testLanguagesEnumCreation" # or a single test method only +``` - 3. You can run all tests via JUnit. +The api tests (in `ors-api/src/test/java/org/heigit/ors/apitests`) are excluded by default. +To include them, add the option `-Papitests`, e.g.: + +```shell +mvn clean verify -Papitests +``` + +If you want to run maven tasks without tests, add the option`-DskipTests`, e.g.: + +```shell +mvn clean package -DskipTests +``` ## Integrating GraphHopper diff --git a/docs/run-instance/configuration/index.md b/docs/run-instance/configuration/index.md index 864a1c275d..281148290f 100644 --- a/docs/run-instance/configuration/index.md +++ b/docs/run-instance/configuration/index.md @@ -1,20 +1,7 @@ # Configuration -The recommended way to configure your own openrouteservice instance is with a YAML configuration file. - -In the past openrouteservice was configured [via JSON file](json.md). This configuration method has been **deprecated** and will be eventually removed, therefore we strongly discourage you from using it. - ## File location -By default, openrouteservice will look for a configuration file in the locations below in that order. -The first existing file is used as configuration. - -| Path | Description | -|:--------------------------------------------|:--------------------------------------------| -| `./ors-config.yml` | Current working directory | -| `~/.config/openrouteservice/ors-config.yml` | User configuration directory | -| `/etc/openrouteservice/ors-config.yml` | Global configuration directory | - There are two (optional) ways for you to provide openrouteservice the location of a configuration file: 1. Program argument ```shell @@ -25,26 +12,67 @@ 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. + +[//]: # (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. + +| Path | Description | +|:--------------------------------------------|:--------------------------------------------| +| `./ors-config.yml` | Current working directory | +| `~/.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. +::: -## File content +## File Formats -You can find an [example configuration file](https://github.com/GIScience/openrouteservice/blob/main/ors-config.yml) with most available configuration options. +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). -At the very least, openrouteservice needs the configuration to contain an enabled [profile](ors/engine/profiles.md) and the -reference to an [OSM data file](/run-instance/data.md#osm-data) to run properly. Therefore, the minimal valid content of such a file -would be, e.g.: +* `.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. +* `.json` config file: In the past openrouteservice was configured [via JSON file](json.md). This configuration method has been **deprecated** and will be eventually removed, therefore we strongly discourage you from using it. If you have an old JSON config, please consider to [migrate to the new config](migrate-from-json.md). + +All of the above described config files can contain the same logic application properties. +For example, the property `ors.engine.profiles.car.enabled` would look like this + +in `*.yml` ```yaml ors: engine: - source_file: ./osm_file.pbf profiles: car: enabled: true ``` +in `*.env` +```shell +ors.engine.profiles.car.enabled=true +``` + +in `*.properties` +```properties +ors.engine.profiles.car.enabled=true +``` + +In [Alternative Configuration](#alternative-configuration) you find the syntax to define the property as environment variable or program argument. + + +## File Content + + The properties are organized in a hierarchical structure, with the following ones at top level. - [Spring Properties](spring/index.md), such as @@ -56,8 +84,20 @@ The properties are organized in a hierarchical structure, with the following one * [ors.cors](ors/cors/index.md): Cross-origin resource sharing settings. * [ors.messages](ors/messages/index.md): System messages that can be sent with API responses following simple rules. +At the very least, openrouteservice needs the configuration to contain an enabled [profile](ors/engine/profiles.md) and the +reference to an [OSM data file](/run-instance/data.md#osm-data) to run properly. Therefore, the minimal valid content of such a file +would be, e.g.: + +```yaml +ors: + engine: + source_file: ./osm_file.pbf + profiles: + car: + enabled: true +``` -## Alternative configuration +## Alternative configuration All configuration parameters can be overridden by runtime parameters or by setting environment variables. At program start openrouteservice reports on every environment variable that *might* have an effect on its behavior. You can run openrouteservice entirely without a configuration file by setting all required properties via environment variables. The examples listed below achieve the same example minimal configuration mentioned above. diff --git a/docs/run-instance/configuration/json.md b/docs/run-instance/configuration/json.md index 5e50860ca7..402de8c005 100644 --- a/docs/run-instance/configuration/json.md +++ b/docs/run-instance/configuration/json.md @@ -4,8 +4,11 @@ The ors-config.json is deprecated! ::: -The "old" configuration method is supported for a while for convenience. The description below is kept as long as openrouteservice still supports configuration via JSON file, but we do **not** recommend using this configuration -method.Note that currently all settings in a provided JSON configuration file will **override** any settings in the YAML file. +The "old" configuration method is supported for a while for convenience. +The description below is kept as long as openrouteservice still supports configuration via JSON file, +but we do **not** recommend using this configuration method. +Please consider to [migrate JSON configuration](migrate-from-json.md) to the new style. +Note that currently all settings in a provided JSON configuration file will **override** any settings in the YAML file. ## ors diff --git a/docs/run-instance/configuration/migrate-from-json.md b/docs/run-instance/configuration/migrate-from-json.md new file mode 100644 index 0000000000..b29c7a7b2d --- /dev/null +++ b/docs/run-instance/configuration/migrate-from-json.md @@ -0,0 +1,3 @@ +# Migrate JSON Config to New Style + +[//]: # (TODO write) \ No newline at end of file diff --git a/docs/run-instance/data.md b/docs/run-instance/data.md index ddb561292b..9116c5fdff 100644 --- a/docs/run-instance/data.md +++ b/docs/run-instance/data.md @@ -1,20 +1,58 @@ -# Data +# Folders and Files + +## Input Files + +The most important input file is the config file. +In [Configuration](/run-instance/configuration/index.md) you find everything about configuration options and files. + Openrouteservice makes use of public open-source data. To generate the best routes, a number of different datasets are used. -## OSM Data +### OSM Data The base data used for the road network and related information (road type, access restrictions etc.) is [OpenStreetMap](https://openstreetmap.org) (OSM). This dataset is a free and open dataset that can be edited by anyone. You can download the latest OSM dataset from https://planet.openstreetmap.org/ or regional extracts from http://download.geofabrik.de/. -## Elevation +The OSM file to be used needs be configured with the property [`ors.engine.source_file`](/run-instance/configuration/ors/engine/index.md). + +### Elevation The data used for elevation are [SRTM](http://srtm.csi.cgiar.org/) and [GMTED](https://www.usgs.gov/coastal-changes-and-impacts/gmted2010). -## Population +Configuration: [`ors.engine.elevation`](/run-instance/configuration/ors/engine/elevation.md) + +### Population When requesting isochrones, you can also request to get population data for the isochrone areas. The data used for this is the [Global Human Settlement Layer (GHSL)](https://ghsl.jrc.ec.europa.eu/ghs_pop2023.php) from the European Commission. Note, that while the dataset was published in 2023, the most recent data contained is from 2020. This is used by the openrouteservice at a resolution of 100m. -## Borders +### Borders Data relating to the avoid borders features is derived from administrative boundaries features in OpenStreetMap. Information about open borders is obtained from [Wikipedia](https://en.wikipedia.org/wiki/Open_border). -## Green & Quiet +Configuration parameters: [`ors.engine.profiles.*.ext_storages.Borders`](/run-instance/configuration/ors/engine/profiles.md#borders) + +### 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/) + +Configuration parameters: [`ors.engine.profiles.*.ext_storages`](/run-instance/configuration/ors/engine/profiles.md#ext-storages) + + +## Output Files + +Openrouteservice produces output files of three types, for which the paths can be configured. The directories these paths point to need to be *writable*. + +### Graphs + +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). + +### Elevation Cache + +If elevation is activated in the configuration, openrouteservice will download and cache the elevation data tiles in a directory +which can be configured with the property [`ors.engine.elevation.cache_path`](/run-instance/configuration/ors/engine/index.md). + +### Logs + +Log output is written to auto-rotated log files. +See chapter [logging](/run-instance/configuration/spring/logging.md) for details on configuring the location of log files. + + + diff --git a/docs/run-instance/index.md b/docs/run-instance/index.md index a360a83893..7e30a7bbb0 100644 --- a/docs/run-instance/index.md +++ b/docs/run-instance/index.md @@ -1,60 +1,32 @@ -# Run your own instance +# Run 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. There are multiple options to achieve this. +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. -The service can exist or be built in the form of 4 different artifact types: +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. -* **WAR:** Like older versions, ORS v8 can still be built as a Web Application Resource/Web ARchive (WAR) which can be deployed into a web container like tomcat. -* **JAR:** Since v8, 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. -* **Docker Image with WAR:** Docker images for ORS versions before v8 were built with a openrouteservice WAR that was running in a tomcat inside a Docker container. If required, you can still go this way, but it is no longer supported by the ORS team. -* **Docker Image with JAR:** Since v8, the docker images, that are created by the ORS team and published on [docker hub](https://hub.docker.com/r/openrouteservice/openrouteservice) contain an ORS fat JAR with an embedded tomcat. +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. -In the table below, we link the documentation for downloading or building the different artifact types, -how to configure and run the service and where to find logs for trouble shooting: +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. -| Artifact | Build yourself | or Download | Configure | Run | Trouble shoot | -|--------------------|-------------------------------------------------|-------------------------------------------------------|---------------------------------------------------------|---------------------------------------------|---------------------------------------------------------------| -| WAR | [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) | -| JAR | [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) | -| Docker Image (WAR) | see [older versions](...?) | no longer supported since v8 | [Configure Docker Image (WAR)](war-docker/configure.md) | [Run docker (WAR)](war-docker/run.md) | [Troubleshoot docker (WAR)](war-docker/troubleshoot.md) | -| Docker Image (JAR) | [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) | +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) | + +[//]: # (TODO add row for rpm package once integrated) + ::: tip We recommend to use one of the JAR options, plain or with docker. ::: - - -## Quick start - -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. - - -## Developer options - -Of course, developers can also build a WAR or JAR or docker Image as described in the linked documentations, -but there is also the option to run openrouteservice directly - -* [from an IDE](runDirectlyFromIDE.md) with specific run configurations -* [on the command line with maven](runDirectlyWithMaven.md) - -## RPM Package - -A new way to install openrouteservice ist RPM. - -[//]: # (TODO describe) - - -## Prerequisites - -Before you start with one of the mentioned options, -please read the documentation regarding [System Requirements](system-requirements) and [Data](data)! diff --git a/docs/run-instance/installation/index.md b/docs/run-instance/installation/index.md deleted file mode 100644 index 2b1bf36ec7..0000000000 --- a/docs/run-instance/installation/index.md +++ /dev/null @@ -1,9 +0,0 @@ -# Installation - -There are multiple possible ways to run your own openrouteservice instance. The most convenient way is to use [Docker](https://www.docker.com/) to run openrouteservice within a container, with a hosted Docker image or building from source. Alternatively, you can either run openrouteservice stand-alone by running the JAR file, or use the WAR file within an [Apache Tomcat](https://tomcat.apache.org/) installation. If you want to customize your instance further than what is possible already by configuration, you can also locally build from source. For further instructions refer to the following documents: - -* [Running with Docker](running-with-docker) -* [Running JAR / WAR](running-jar-war) -* [Building from Source](building-from-source) - -For more information on configuring openrouteservice for your specific needs, also see the [configuration](/run-instance/configuration/index.md) documentation. \ No newline at end of file diff --git a/docs/run-instance/installation/running-jar-war.md b/docs/run-instance/installation/running-jar-war.md deleted file mode 100644 index 79398c3901..0000000000 --- a/docs/run-instance/installation/running-jar-war.md +++ /dev/null @@ -1,46 +0,0 @@ -# Running JAR / WAR - -[//]: # (TODO: overhaul contents after integrating the jar build PR) - -## Provided artifacts - -For release version 8.0.0 and newer, we provide JAR and WAR files as artifacts for download. The JAR file can be run stand-alone and will start openrouteservice using a built-in Tomcat server. Alternatively, you can set up your own Tomcat instance on your server and deploy the WAR artifact on it. - -## Parameters and environment variables - -Openrouteservice can be configured in several ways, described in detail in the chapter on [configuration](/run-instance/configuration/index.md). - -If you already have an old and deprecated JSON format configuration file, you can still use that configuration file by setting an environment variable called `ORS_CONFIG` to point that file. Currently, all settings in a provided JSON configuration file will *override* any settings in the YAML file. We strongly recommend to migrate your settings to the new YAML format though, since we are planning to remove the support for JSON configuration files with the next major version release. - -## Folders and files - -Openrouteservice produces output files of three types, for which the paths can be configured. The directories these paths point to need to be *writable*. The default configuration file for openrouteservice mentioned above provides the following paths: -- `./ors-core/data/graphs`: The converted graphs for the profiles are stored here. -- `./ors-core/data/elevation_cache`: If elevation is activated in the configuration, openrouteservice will download and cache the elevation data tiles here. -- `./logs`: Log output is written to auto-rotated log files. - -Openrouteservice also requires an OpenStreetMap export file to import the graph data from, configured in the YAML configuration file. The default location is `./ors-core/data/osm_file.pbf`. - -See chapter [logging](/run-instance/configuration/spring/logging.md) for details on configuring the location of log files, and chapter [engine](/run-instance/configuration/ors/engine/index.md) for the all other file locations. - -# Installing and running openrouteservice within Tomcat 10 - -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 you downloaded (or built, in which case the file can be found at `ors-api/target`) 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/jar-docker/build.md b/docs/run-instance/jar-docker/build.md index 8e7fe6d0a7..204f04bfbf 100644 --- a/docs/run-instance/jar-docker/build.md +++ b/docs/run-instance/jar-docker/build.md @@ -1 +1,6 @@ -# Build Docker Image with openrouteservice JAR \ No newline at end of file +# 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 index 27606acc50..30706e6bc9 100644 --- a/docs/run-instance/jar-docker/configure.md +++ b/docs/run-instance/jar-docker/configure.md @@ -1 +1,10 @@ -# Configure Docker Image with openrouteservice JAR \ No newline at end of file +# 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/index.md b/docs/run-instance/jar-docker/index.md new file mode 100644 index 0000000000..fd40910d9e --- /dev/null +++ b/docs/run-instance/jar-docker/index.md @@ -0,0 +1,4 @@ + + + + diff --git a/docs/run-instance/jar-docker/run.md b/docs/run-instance/jar-docker/run.md index 2834fcebe5..5b5a9ca421 100644 --- a/docs/run-instance/jar-docker/run.md +++ b/docs/run-instance/jar-docker/run.md @@ -1 +1,19 @@ -# Run Docker Image with openrouteservice JAR \ No newline at end of file +# 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/build.md b/docs/run-instance/jar/build.md index 79446c13b9..68e07c8fe2 100644 --- a/docs/run-instance/jar/build.md +++ b/docs/run-instance/jar/build.md @@ -1 +1,28 @@ -# Build openrouteservice JAR \ No newline at end of file +# 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/index.md b/docs/run-instance/jar/index.md new file mode 100644 index 0000000000..03da6c0b7f --- /dev/null +++ b/docs/run-instance/jar/index.md @@ -0,0 +1,5 @@ +# 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/war-docker/build.md b/docs/run-instance/war-docker/build.md index 1197f2067f..666004c3de 100644 --- a/docs/run-instance/war-docker/build.md +++ b/docs/run-instance/war-docker/build.md @@ -1 +1,7 @@ -# Build Docker Image with openrouteservice WAR \ No newline at end of file +# 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/index.md b/docs/run-instance/war-docker/index.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/run-instance/war/build.md b/docs/run-instance/war/build.md index 983b66b26e..fbb5d76b6e 100644 --- a/docs/run-instance/war/build.md +++ b/docs/run-instance/war/build.md @@ -1 +1,23 @@ -# Build openrouteservice WAR \ No newline at end of file +# 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 index 9ae7392261..508103035e 100644 --- a/docs/run-instance/war/configure.md +++ b/docs/run-instance/war/configure.md @@ -1 +1 @@ -# Configure openrouteservice WAR \ No newline at end of file +# Configure openrouteservice WAR diff --git a/docs/run-instance/war/download.md b/docs/run-instance/war/download.md index bdc14412b1..f1b4c0c504 100644 --- a/docs/run-instance/war/download.md +++ b/docs/run-instance/war/download.md @@ -1 +1,4 @@ -# Download openrouteservice WAR \ No newline at end of file +# 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 new file mode 100644 index 0000000000..da926445dc --- /dev/null +++ b/docs/run-instance/war/index.md @@ -0,0 +1,4 @@ +# 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 index 5c563bc28c..d6125bfad7 100644 --- a/docs/run-instance/war/run.md +++ b/docs/run-instance/war/run.md @@ -1 +1,23 @@ -# Run openrouteservice WAR \ No newline at end of file +# 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.