Skip to content
Klutch.sh Docs

Deploying an Openrouteservice App

Introduction

Openrouteservice (ORS) delivers routing, geocoding, isochrones, and matrix services using OpenStreetMap data. This guide targets worldwide coverage with preprocessed graphs supplied externally. Deploying ORS with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for configs and logs—all configured from klutch.sh/app. You’ll mount your prebuilt graphs and keep data out of the image for faster, smaller deployments.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your ORS Dockerfile (GitHub is the only supported git source)
  • Preprocessed worldwide ORS graphs stored externally (provide a mounted path)
  • Adequate storage for graphs, logs, and caches

For onboarding, see the Quick Start.

Architecture and ports

  • ORS REST API serves HTTP on internal port 8080; choose HTTP traffic.
  • Persistent storage is required for mounted graphs and logs.

Repository layout

openrouteservice/
├── Dockerfile              # Must be at repo root for auto-detection
├── conf/                   # application.yml and profiles
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub (assuming graphs are mounted to /ors-graphs):

Terminal window
docker build -t ors-local .
docker run -p 8080:8080 \
  -e ORS_PROFILES="car,bike,foot" \
  -v /path/to/graphs:/ors-graphs \
  ors-local

Dockerfile for Openrouteservice (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM ghcr.io/gis-ops/openrouteservice:latest


# Set the internal port ORS will listen on
ENV PORT=8080 \
    JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g"


WORKDIR /ors


# Copy custom configuration if needed
COPY conf /ors/conf


EXPOSE 8080
CMD ["./bin/ors-server", "--spring.profiles.active=default", "--server.port=8080"]

Notes:

  • Pin the image tag (e.g., ghcr.io/gis-ops/openrouteservice:v8.x) for stability; update intentionally.
  • JVM opts should match your memory allocation; adjust JAVA_TOOL_OPTIONS.
  • Graphs are not baked into the image; mount them at runtime.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • PORT=8080
  • ORS_PROFILES=car,bike,foot (list of enabled profiles matching your preprocessed graphs)
  • JAVA_TOOL_OPTIONS=-Xms2g -Xmx4g (tune to your memory limits)
  • Optional: LOGGING_LEVEL_ROOT=INFO, provider API keys if you use external geocoding/POI services.

If you deploy without the Dockerfile and need Nixpacks overrides (not typical for ORS):

  • NIXPACKS_START_CMD=./bin/ors-server --spring.profiles.active=default --server.port=8080

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /ors-graphs — your preprocessed worldwide graphs (mounted from your external storage).
  • /ors/logs — logs and diagnostics.

Ensure these paths are writable (logs) and readable (graphs) inside the container.

Deploy Openrouteservice on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 8080.
  4. Add the environment variables above, including ORS_PROFILES and JVM settings.
  5. Attach persistent volumes for /ors-graphs (preprocessed graphs) and /ors/logs, sizing them for your datasets and log retention.
  6. Deploy. Your Openrouteservice API will be reachable at https://example-app.klutch.sh; point clients to this URL.

Sample API usage

Route request (car profile):

Terminal window
curl -X POST "https://example-app.klutch.sh/ors/v2/directions/driving-car" \
  -H "Content-Type: application/json" \
  -d '{ "coordinates": [[8.681495, 49.41461], [8.687872, 49.420318]] }'

Isochrone:

Terminal window
curl -X POST "https://example-app.klutch.sh/ors/v2/isochrones/driving-car" \
  -H "Content-Type: application/json" \
  -d '{ "locations": [[8.681495, 49.41461]], "range": [600] }'

Health checks and production tips

  • Add an HTTP probe to /ors/v2/health or /health if enabled.
  • Enforce HTTPS at the edge; forward internally to port 8080.
  • Monitor heap and disk usage; resize /ors-graphs and /ors/logs before they fill.
  • Pin image versions; test upgrades in staging. Keep a backup of your preprocessed graphs.
  • Align ORS_PROFILES with the graph data you mounted to avoid startup errors.

Openrouteservice on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 8080 configured, and externally preprocessed worldwide graphs mounted, you can deliver global routing and geospatial APIs without extra YAML or workflow overhead.