OpenRouteService Guide
This section is an installation and administration guide for deploying OpenRouteService (ORS) in a Linux environment using Docker and Docker Compose (this can be hosted on any docker platform). ORS is a routing engine that processes OpenStreetMap (OSM) data to generate routes, matrices, travel distances, and related geospatial calculations. The guide provides a full technical blueprint for setting up the ORS environment, including system prerequisites, user and directory setup, map data acquisition, and the construction of a combined OSM dataset for use by the routing engine. It also includes the ORS configuration file required to define routing profiles, API limits, and system-level behaviors.
Beyond installation, the document serves as an operational reference for maintaining, rebuilding, and securing the ORS instance. It outlines commands for starting, stopping, and monitoring the Docker container, rebuilding routing graphs, managing logs, and performing backups. It also includes troubleshooting steps for common issues such as failed graph builds, API errors, permission problems, and port conflicts. Overall, the guide provides everything needed to deploy a production-ready ORS installation and keep it running reliably in a managed environment.
- Service name: ors-app
- Docker image: openrouteservice/openrouteservice:latest
- Operating system: Rocky Linux 9 (or later)
- Supported map region:
Pre-Requisites
1. System Requirements
| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 4 cores | 8 cores or more |
| RAM | 8 GB | 16 GB+ (ORS graph building is memory intensive) |
| Disk Space | 40 GB | 80 GB+ (depending on OSM extract size) |
| Internet Access | Required | Required |
2. Software Requirements
| Component | Requirement | Notes |
|---|---|---|
| Docker Engine | Installed & running | Version 24 or later |
| Docker Compose | Installed | v2.x or later |
| Java | Included in container | Not required on host |
| curl, wget, tar | Installed | For downloading maps and verification |
Note: Docker installation is assumed complete and functional.
Installation Steps
Follow these steps to install and configure OpenRouteService.
1. Create the helix user and assign Docker permissions
| sudo useradd -m -s /bin/bash helix |
| sudo passwd helix |
| sudo usermod -aG docker helix |
| su - helix |
2. Create the directory structure for ORS
| mkdir p /home/helix/ors/{elevation_cache,graphs,logs,files} sudo chown R helix:helix /home/helix/ors |
3. Download the OSM Maps files for supported regions
| cd /home/helix/ors/files |
| wget https://download.geofabrik.de/north-america/us/georgia-latest.osm.pbf |
| wget https://download.geofabrik.de/north-america/us/nevada-latest.osm.pbf |
| wget https://download.geofabrik.de/africa/south-africa-latest.osm.pbf |
NOTE: For this setup, we will combine the .pbf files. It’s cleaner, to have one container per region, it avoids massive graph builds, and simplifies maintenance.
4. Combine OSM Maps files
| cd /home/helix/ors/files |
| sudo dnf install osmctools |
| osmconvert south-africa-latest.osm.pbf georgia-latest.osm.pbf nevada-latest.osm.pbf -o=combined.osm.pbf |
cd /mnt/ors/files
5. Convert each PBF to O5M format
| osmconvert south-africa-latest.osm.pbf -o=south-africa.o5m |
| osmconvert georgia-latest.osm.pbf -o=georgia.o5m |
| osmconvert nevada-latest.osm.pbf -o=nevada.o5m |
6. Merge all three O5M files
| osmconvert south-africa.o5m georgia.o5m nevada.o5m -o=combined.o5m |
7. Convert back to PBF
| osmconvert combined.o5m -o=combined.osm.pbf |
8. Clean up intermediate files
| rm south-africa.o5m georgia.o5m nevada.o5m combined.o5m |
9. Set proper permissions
| sudo chown 1000:1000 combined.osm.pbf |
Create the Files
1. Create the ORS Configuration file /home/helix/ors/ors-config.yml with the following contents:
ors:
engine:
profile_default:
build:
source_file: /home/ors/files/combined.osm.pbf
profiles:
driving-car:
enabled: true
services:
routing:
enabled: true
api_settings:
maximum_locations: 100
maximum_visited_nodes: 1000000
maximum_range: 3000000
endpoints:
matrix:
enabled: true
maximum_routes: 10000 # Default is 2500; increase as needed for larger origin-destination sets (e.g., 100x100 matrix = 10,000 routes)
maximum_routes_flexible: 1000
maximum_visited_nodes: 1000000 # Increase if you get errors about visited nodes during computation
maximum_search_radius: 3000000 # In meters; adjust if points are far apart
2. Create the Docker Compose File at /home/helix/ors/docker-compose.yml with the following configuration:
services:
ors-app:
image: openrouteservice/openrouteservice:latest
container_name: ors-app
user: "1000:1000"
ports:
- "8082:8082"
volumes:
- /mnt/ors/:/home/ors/config
- /mnt/ors/elevation_cache:/home/ors/elevation_cache
- /mnt/ors/graphs:/home/ors/graphs
- /mnt/ors/logs:/home/ors/logs
- /mnt/ors/files:/home/ors/files
environment:
- REBUILD_GRAPHS=True
- JAVA_OPTS=-Xms4g -Xmx8g
- CONTAINER_LOG_LEVEL=DEBUG
- ors.engine.profile_default.service.maximum_distance=3000000
- ors.engine.profile_default.service.maximum_distance_dynamic_weights=3000000
- ors.engine.profile_default.service.maximum_distance_avoid_areas=3000000
- ors.engine.profile_default.service.maximum_waypoints=50
- ors.engine.profile_default.service.maximum_snapping_radius=400
- ors.engine.profile_default.service.maximum_distance_alternative_routes=3000000
restart: unless-stopped
Finish Up
1. Start the OpenRouteService Container
| docker pull openrouteservice/openrouteservice:latest |
| cd /home/helix/ors docker compose up -d |
2. Verify ORS Startup
| docker ps docker logs -f ors-app curl http://localhost:8082/ors/v2/health |
3. Maintenance
Use the following commands for container lifecycle management:
| Start: docker compose up -d |
| Stop: docker compose down |
| Restart: docker compose restart |
| Logs: docker logs -f ors-app |
4. To rebuild routing graphs
| docker compose down rm -rf /home/helix/ors/graphs/* docker compose up -d |
5. Backup and Recovery
Back up configuration, logs, and optionally graph data regularly. Example backup command:
| tar czf /home/helix/backups/ors_backup_$(date +%Y%m%d).tar.gz /home/helix/ors |
6. Security Recommendations
- Run ORS as helix:helix user (non-root).
- Restrict access to port 8082 with a firewall or reverse proxy.
- Use HTTPS if exposed externally.
- Regularly update the ORS Docker image:
| docker compose pull |
| docker compose up -d |
7. Troubleshooting
- Common issues and resolutions:
| ORS stuck on startup → Graph build in progress (check logs) |
| API returns 500 error → Rebuild graphs |
| Port 8082 in use → Change port mapping in docker-compose.yml |
| Permission denied → Ensure helix:helix ownership of /home/helix/ors |