Skip to content

Commit

Permalink
docs(run-instance): migrated content to new structure
Browse files Browse the repository at this point in the history 
also added and updated things on the fly
  • Loading branch information
@jhaeu
jhaeu committed Feb 16, 2024
1 parent bb8540d commit 4b11b20
Show file tree
Hide file tree
Showing 25 changed files with 348 additions and 209 deletions.
70 changes: 32 additions & 38 deletions docs/.vitepress/config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/',
Expand Down Expand Up @@ -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'}
]},
]
},
{
Expand Down
2 changes: 1 addition & 1 deletion docs/contributing/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
9 changes: 0 additions & 9 deletions docs/contributing/opening-project-in-intellij.md
View file

This file was deleted.

2 changes: 1 addition & 1 deletion docs/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
64 changes: 46 additions & 18 deletions ...ance/installation/building-from-source.md → docs/run-instance/building-from-source.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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=<config>` 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
Expand Down
Loading

0 comments on commit 4b11b20

Please sign in to comment.