Merge pull request #22 from GIScience/development

Instructions for installation
GIScience · Sep 16, 2017 · 966fd2c · 966fd2c
2 parents 05ffad9 + dc3376c
commit 966fd2c
Show file tree

Hide file tree

Showing 13 changed files with 110 additions and 188 deletions.
diff --git a/Jenkinsfile b/Jenkinsfile
@@ -1,5 +1,3 @@
-//properties([pipelineTriggers([githubPush()])])
-
 node {
    def mvnHome
    stage('Preparation') { // for display purposes
@@ -14,7 +12,8 @@ node {
     stage('build-ors') {
         sh "cp ${WORKSPACE}/openrouteservice-api-tests/conf/app.config.test ${WORKSPACE}/openrouteservice/WebContent/WEB-INF/app.config"
         sh "'${mvnHome}/bin/mvn' -f ${WORKSPACE}/openrouteservice/pom.xml install -B"
-        archive "${WORKSPACE}/openrouteservice/target/*.war" 
+        archiveArtifacts artifacts: '**/*.war', fingerprint: true
+
     }
 
     stage('test-ors') {

diff --git a/README.md b/README.md
@@ -36,7 +36,13 @@ If you want to do contribute your improvements, please follow these steps:
 
 ## Installation
 
-Instructions on how to install openrouteservice will follow soon.
+We suggest using docker to install and launch OpenRouteService backend. In short, run the following command under the source code tree will get everything done.
+
+```bash
+cd docker && docker-compose up
+```
+
+For more details, check the [docker installation guide](docker/README.md).
 
 ## Usage
 

diff --git a/docker/README.md b/docker/README.md
@@ -0,0 +1,53 @@
+# Install and Run OpenRouteService Backend via Docker
+
+It's possible and easy to install and launch the OpenRouteService backend service with Docker. Please note that the [Dockerfile](../Dockerfile) under the repository root directory is only for building the [WAR file](https://www.wikiwand.com/en/WAR_(file_format)).
+
+## Short version
+
+run the following command within this `docker/` directory:
+
+```bash
+docker-compose up
+```
+
+It will:
+
+1. build and test the OpenRouteService core from the local codebase with the `docker/conf/app.config.sample` as the config and the dataset for Heidelberg under `docker/data/` as sample data;
+2. generate the built `ors.war` file and expose it to `docker/build/` directory;
+3. launch the OpenRouteService backend service on port `8080`.
+
+The service status is queryable via `http://localhost:8080/ors/health` endpoint. When the service is ready, go to `http://localhost:8080/ors/status` and it will show more detailed information. A URL for test can be `http://localhost:8080/ors/routes?profile=foot-walking&coordinates=8.676581,49.418204|8.692803,49.409465`. It should be able to provide the recommanded walking path in JSON format.
+
+## Long version
+
+### WAR file building
+
+For building the WAR file only, either run
+
+```bash
+docker run -v /Users/user/build:/ors-core/build giscience/openrouteservice
+```
+
+or
+
+```bash
+docker-compose up ors-build
+```
+
+If everything goes fine, the built `ors.war` file can be found under the host directory, e.g. `/Users/user/build` in the above `docker run` command or `./build/` in the `docker-compose` command.
+
+### Run OpenRouteService
+
+No matter whether the WAR file has been built or not, run
+
+```bash
+docker-compose up
+```
+
+will get everything done with the sample Heidelberg dataset.
+
+### Run with your own OSM dataset
+
+Prepare the OSM dataset (formats support `.osm`, `.osm.gz`, `.osm.zip`, `.pbf`) in the `docker/data/` directory. Make your own `app.config` (check the sample with detailed comments [here](../openrouteservice/WebContent/WEB-INF/app.config.sample) for reference) and change the `APP_CONFIG` variable in `docker-compose.yml` to let it point to your customized `app.config`. Then, run `docker-compose up`.
+
+It should be noticed that if your dataset is very big, please adjust the `-Xmx` parameter of `JAVA_OPTS` in `docker-compose.yml`. According to our experiences, it should be at least `180g` for the whole globe.
diff --git a/openrouteservice-api-tests/.classpath b/openrouteservice-api-tests/.classpath
diff --git a/openrouteservice-api-tests/.settings/org.eclipse.core.resources.prefs b/openrouteservice-api-tests/.settings/org.eclipse.core.resources.prefs
diff --git a/openrouteservice-api-tests/.settings/org.eclipse.jdt.core.prefs b/openrouteservice-api-tests/.settings/org.eclipse.jdt.core.prefs
diff --git a/openrouteservice-api-tests/.settings/org.eclipse.m2e.core.prefs b/openrouteservice-api-tests/.settings/org.eclipse.m2e.core.prefs
diff --git a/openrouteservice/WebContent/WEB-INF/app.config.sample b/openrouteservice/WebContent/WEB-INF/app.config.sample
@@ -1,30 +1,45 @@
 {
 	ors {
+	    # The topmost element for parameterization of ORS end-points such as Routing, Geocoding, Isochrones, etc.
 		services: {
+            # An end-point used to shorten links. 
 			shortenlink: {
+			    # Enables or disables (true/false) the end-point. Default value is true.
 				enabled: true,
 				user_name: YOUR_USER,
 				user_password: YOUR_PASSWORD,
 				api_key: YOUR_API_KEY,
-				attribution: "openrouteservice.org, OpenStreetMap contributors"
 			}
+			# Accessibility API end-point parameters
+			# NOTE: not ready for production yet.
 			accessibility: {
+			    # Enables or disables (true/false) the end-point. Default value is true.
 	        	enabled: true,
 	        	maximum_range_distance: 120000,
 	        	maximum_range_time: 3600,
 	        	maximum_locations: 2,
 	        	route_details_allowed: true,
 	        	attribution: "openrouteservice.org, OpenStreetMap contributors"
-	    	}			
+	    	}		
+			# Matrix API end-point parameters			
         	matrix: {
+			    # Enables or disables (true/false) the end-point. Default value is true.
         	    enabled: true,
-                maximum_locations: 200,
+				# Maximum dimension of the result matrix. In other words, the maximum possible length of a row or a column in the matrix.
+				# Default value is 100.
+                maximum_locations: 100,
+				# Maximum allowed distance between the requested coordinate and a point on the nearest road. The value is measured in meters.
                 maximum_search_radius: 5000,
+				# Maximum allowed number of visited nodes in shortest path computation. This threshold is applied only for Dijkstra algorithm. 
                 maximum_visited_nodes: 100000,
+				# Specifies whether the name of a neares street to the location can be resolved or not. Default value is true.
                 allow_resolve_locations: true,
                 attribution: "openrouteservice.org, OpenStreetMap contributors"
             }
+			# Optimization API end-point parameters
+			# NOTE: not ready for production yet.
             optimization: {
+			    # Enables or disables (true/false) the end-point. Default value is true.
                 enabled: true,
                 maximum_locations: 200,
                 solver_name: "default",
@@ -33,16 +48,20 @@
                 }
                 attribution: "openrouteservice.org, OpenStreetMap contributors"
             }
+			# MapMatching API end-point parameters
+			# NOTE: not implemented yet.
             mapmatching: {
+			    # Enables or disables (true/false) the end-point. Default value is true.
         	    enabled: true,
                 maximum_locations: 100,
                 maximum_search_radius: 200,
                 maximum_visited_nodes: 10000,
                 attribution: "openrouteservice.org, OpenStreetMap contributors"
             }
+			# Isochrones API end-point parameters
 			isochrones: {
-				enabled: true,
-				# possible values for maximum_range_distance and maximum_range_time are an integer or a list of values specifically defined for each profile
+			    # Enables or disables (true/false) the end-point.
+				# Possible values for maximum_range_distance and maximum_range_time are an integer or a list of values specifically defined for each profile.
 				maximum_range_distance: 
 				[ 
 				   { profiles: "any", value: 50000 }
@@ -58,24 +77,28 @@
 				allow_compute_area: true,
 				attribution: "openrouteservice.org, OpenStreetMap contributors"
 			}
+			# Geocoding API end-point parameters
 			geocoding: {
+				# Enables or disables (true/false) the end-point. Default value is true.
             	geocoder_name: pelias,
-                geocoding_url: "http://129.206.7.154:3100/v1/search",
-                reverse_geocoding_url: "http://129.206.7.154:3100/v1/reverse",
+                geocoding_url: "http://YOUR_ADDRESS/v1/search",
+                reverse_geocoding_url: "http://YOUR_ADDRESS/v1/reverse",
                 response_limit: 20,
-                user_agent: openrouteservice.org,
+                user_agent: OpenRouteService,
                 attribution: "openrouteservice.org, OpenStreetMap contributors"
             }
+			# Locations API end-point parameters
 			locations: {
+				# Enables or disables (true/false) the end-point. Default value is true.
 				enabled: true,
 				provider_name: postgresql,
 				provider_parameters: {
-					host: "129.206.7.206",
+					host: "YOUR_HOST",
 					port: 5432,
-					db_name: "gis",
-					user: "admin", 
-					password : "gZwe5Nj", 
-					table_name : "planet_osm_pois_42"
+					db_name: "YOUR_DATABASE",
+					user: "YOUR_USER", 
+					password : "YOUR_PASSWORD", 
+					table_name : "YOUR_TABLE"
 				},
 				response_limit: 1000,
 				maximum_categories: 5,
@@ -89,12 +112,14 @@
 				maximum_search_radius_for_polygons: 1000,
 				attribution: "openrouteservice.org, OpenStreetMap contributors"
 			}
+			# Routing API end-point parameters
 			routing: {
+				# Enables or disables (true/false) the end-point. Default value is true.
 				enabled: true,
 				mode: "normal",
 				sources: ["openrouteservice/src/main/files/heidelberg.osm.gz"],
 				init_threads: 2,
-				attribution: "openrouteservice.org, OpenStreetMap contributors, tmc - BASt",
+				attribution: "openrouteservice.org, OpenStreetMap contributors",
 				profiles: {
 					active: ["vehicles", "bike", "bike2", "pedestrian"],
 					default_params: {
@@ -142,7 +167,7 @@
 						    encoder_options : "turn_costs=true|block_fords=false,turn_costs=true|block_fords=false,turn_costs=true|block_fords=false",
                             maximum_distance: 100000,
                             elevation: true, 
-
+                            # parameters for the pre-processing stage
                             preparation:
 							{  
 							    min_network_size: 200,
@@ -165,14 +190,17 @@
 									}
 								}
 							}
+							# parameters for pre-processing the execution stage
 							execution:
 							{
 						    	methods:
 								{
+								    # Contraction hierachies
 									ch:
 									{
 										disabling_allowed: true
 									},
+									# Landmarks
 									lm:
 									{
 										disabling_allowed: true,
@@ -181,14 +209,13 @@
 								}
 							}
 						    ext_storages: {
-                                WayCategory: {
-                                },								
+                                WayCategory: { },								
                                 HeavyVehicle: {
-								    restrictions: true
+									restrictions: true
                                 },								
-								WaySurfaceType: {
-								}
+								WaySurfaceType: { }
 						    }
+							# Traffic feature is not ready for production.
 						    traffic: false
 					    }
 					}
@@ -231,7 +258,6 @@
                                 #NoiseIndex: {
                                 #	 filepath: "PATH/TO/THE_NOISE_INDEX_CSV_FILE"
                                 #},
-
                                 WayCategory: { },								
 								WaySurfaceType: { },
 								HillIndex: { },
@@ -247,10 +273,9 @@
 					extent: "",
 					working_directory: "./update_graphs"
 				}
-
 				traffic: {
 					enabled: false,
-					source: "type=ftp;server=viznrwftp.gewi.com;user=cacc016;password=4)Zn3450;file=viznrw.xml",
+					source: "type=ftp;server=YOUR_SERVER;user=cacc016;password=4)Zn3450;file=viznrw.xml",
 					location_codes_path: "PATH/TO/TMC_LCL_LIST",
 					update_interval: 300000,
 					output_directory: "Temp"

diff --git a/openrouteservice/docs/admin/fail2ban/howto.txt b/openrouteservice/docs/admin/fail2ban/howto.txt
diff --git a/openrouteservice/docs/notes.md b/openrouteservice/docs/notes.md