Go back

Self-Hosted OSRM in Docker

By SumGuy 12 min read
Self-Hosted OSRM in Docker

From “I Want Driving Directions” to “I Own the /route Endpoint”

I started where everyone starts: just use Google Maps Directions API. It’s easy, documented, works. Then a side project got slightly popular, the request count climbed, and I got familiar with the part of the Google Cloud console that shows you a bar chart going up while your wallet goes down.

The thing is, routing algorithms aren’t magic. Dijkstra’s algorithm is textbook computer science. The data behind most commercial routing APIs is OpenStreetMap, same data you can download yourself. The gap between “just use the API” and “run your own” is smaller than it looks — a few hours of prep time, some RAM, and a Compose file that fits on one screen.

OSRM (Open Source Routing Machine) is the routing engine that actually lives up to that promise. Sub-millisecond route calculations on precomputed graphs, proper turn restrictions, pedestrian and bicycle profiles, real /route and /table endpoints. And you own the whole thing.

Full example: Compose, prep scripts, and sample profiles at github.com/KingPin/sumguy-examples/tree/main/self-hosting/self-hosted-osrm-docker

Step Zero: Get Your OSM Data

OSRM is useless without an OSM extract to eat. If you’ve been following along with the self-hosted geocoding setup from earlier this month, you’ve already been through this dance — Geofabrik publishes regional extracts at download.geofabrik.de in .osm.pbf format, organized by continent, country, and subregion.

Pick the smallest extract that covers your use case. Here’s the rough size picture for driving profiles:

For a home lab or a solo dev project, a state or small country is the sweet spot. Download it somewhere permanent:

Terminal window
mkdir -p /opt/osrm/data
cd /opt/osrm/data


# Example: Texas
wget https://download.geofabrik.de/north-america/us/texas-latest.osm.pbf


# Example: Germany
wget https://download.geofabrik.de/europe/germany-latest.osm.pbf

The .osm.pbf is the raw input. OSRM can’t route from it directly — you have to cook it first.

The Four-Step Prep Pipeline

OSRM’s routing is fast because it does the hard graph work offline. You preprocess the map data into a routing graph, then the running server just does fast lookups on that graph. The preprocessing has four steps, and knowing what each one does saves you when something goes wrong.

1. Extract

Terminal window
docker run --rm -v /opt/osrm/data:/data \
  ghcr.io/project-osrm/osrm-backend \
  osrm-extract -p /opt/osrm-backend/profiles/car.lua /data/texas-latest.osm.pbf

This reads the PBF and produces .osrm files — a parsed graph representation that knows about roads, their access rules, and their speeds according to the Lua profile you specify. The -p flag points at a Lua profile file. car.lua is the default for driving. We’ll get to what’s in that file in a minute.

This step is CPU-bound and takes 5–30 minutes depending on region size and hardware. It produces a bunch of files alongside your PBF: texas-latest.osrm, texas-latest.osrm.ebg, texas-latest.osrm.enw, and a bunch more.

2. Partition

Terminal window
docker run --rm -v /opt/osrm/data:/data \
  ghcr.io/project-osrm/osrm-backend \
  osrm-partition /data/texas-latest.osrm

Partition divides the road network into cells — nested geographic partitions that MLD (Multi-Level Dijkstra) uses to speed up routing. If you’re using Contraction Hierarchies instead (more on that shortly), you can skip this step. The MLD pipeline requires both partition and customize. CH skips both and goes straight to contract.

3. Customize (MLD path) or Contract (CH path)

MLD:

Terminal window
docker run --rm -v /opt/osrm/data:/data \
  ghcr.io/project-osrm/osrm-backend \
  osrm-customize /data/texas-latest.osrm

CH:

Terminal window
docker run --rm -v /opt/osrm/data:/data \
  ghcr.io/project-osrm/osrm-backend \
  osrm-contract /data/texas-latest.osrm

osrm-customize injects the speed and turn-penalty data from the Lua profile into the partitioned graph. This is the step that actually bakes speed limits, road type weights, and access rules into the routing graph.

osrm-contract (for CH) computes the contraction hierarchy — a heavily precomputed shortcut graph that collapses millions of routing decisions into a structure the server can search in microseconds.

4. Routed

Once preprocessing is done, the server itself is trivial. The graph is already computed; osrm-routed just serves it.

CH vs MLD: Which Algorithm Should You Pick

This is where most tutorials gloss over something important, and then you get bitten later.

Contraction Hierarchies (CH) precomputes shortcuts across the entire graph. Route queries are extremely fast — we’re talking single-digit milliseconds for typical routes. But the precomputation is total. If you change your Lua profile (different speed limits, access rules, penalties), you throw away osrm-contract’s output and start the contraction step over. For a large region, that’s 30–90 minutes of blocking compute every time you want to tweak something.

Multi-Level Dijkstra (MLD) separates the graph structure (partition, slow, one-time) from the metric data (customize, fast, re-runnable). If you change your speed model or access rules, you only re-run osrm-customize — which is dramatically faster than full re-contraction. The trade-off is that MLD queries are slightly slower than CH queries at runtime, though we’re still talking under 10ms for regional routes on modern hardware.

In practice:

CHMLD
Query speed~1–3ms~5–10ms
Profile change costFull re-contractRe-customize only
Memory useLowerSlightly higher
Best forStable profile, high QPSIterating on profiles

If you’re running a production service with a locked-down profile and you need every last millisecond, use CH. If you’re experimenting with custom speed models or access rules for different vehicle types, use MLD. For a home lab, MLD is almost always the right call — you will want to tweak the profile.

The Compose File

Once the data is prepped, the Compose file is refreshingly simple. The heavy lifting is already on disk.

docker-compose.yml
services:
  osrm:
    image: ghcr.io/project-osrm/osrm-backend:latest
    container_name: osrm
    ports:
      - "5000:5000"
    volumes:
      - /opt/osrm/data:/data
    command: >
      osrm-routed
      --algorithm mld
      /data/texas-latest.osrm
    restart: unless-stopped

For CH, swap --algorithm mld to --algorithm ch. Everything else stays the same — the .osrm file extension is shared between both; the algorithm determines which auxiliary files get read.

A few options worth knowing:

The container starts in seconds since it’s just reading the precomputed graph from disk.

Lua Profiles: Where the Routing Actually Gets Interesting

The .lua profile is what makes OSRM understand what your vehicle can do. OSRM ships three:

The profiles live inside the container at /opt/osrm-backend/profiles/. You can extract them and customize:

Terminal window
docker run --rm ghcr.io/project-osrm/osrm-backend \
  cat /opt/osrm-backend/profiles/car.lua > /opt/osrm/profiles/car.lua

Now mount your custom profiles into the container during the extract step:

Terminal window
docker run --rm \
  -v /opt/osrm/data:/data \
  -v /opt/osrm/profiles:/profiles \
  ghcr.io/project-osrm/osrm-backend \
  osrm-extract -p /profiles/car.lua /data/texas-latest.osm.pbf

Here’s a snippet showing how profiles control speed and access. The key tables to know:

car.lua (excerpt)
-- Speed table for road type → km/h
local speed_profile = {
  motorway        = 90,
  motorway_link   = 45,
  trunk           = 85,
  trunk_link      = 40,
  primary         = 65,
  primary_link    = 30,
  secondary       = 55,
  secondary_link  = 25,
  tertiary        = 40,
  residential     = 25,
  living_street   = 10,
  service         = 15,
  track           = 5,
}


-- Access tags: which values mean "yes, can drive here"
local access_tag_whitelist = Set {
  "yes",
  "motorcar",
  "motor_vehicle",
  "vehicle",
  "permissive",
  "designated",
  "destination",
}

Want to model a delivery van that can’t use residential streets? Drop residential from speed_profile. Want a profile for heavy trucks that avoids low bridges? OSM has maxheight and maxweight tags — the profile can read them. The Lua API gives you access to every tag on every way and node in the dataset.

Every profile change requires re-running osrm-extract plus osrm-customize (MLD) or osrm-contract (CH). There’s no hot-reload. Plan for this.

Making a Real /route Request

Once the container is up:

Terminal window
curl "http://localhost:5000/route/v1/driving/-97.7431,30.2672;-96.7970,32.7767?overview=full&steps=true"

That routes from Austin, TX to Dallas, TX. The response shape looks like this (abbreviated):

{
  "code": "Ok",
  "routes": [
    {
      "distance": 305412.4,
      "duration": 10287.6,
      "geometry": "encodedPolyline...",
      "legs": [
        {
          "distance": 305412.4,
          "duration": 10287.6,
          "steps": [
            {
              "distance": 1203.4,
              "duration": 72.2,
              "name": "Congress Avenue",
              "maneuver": {
                "type": "depart",
                "modifier": "right",
                "bearing_after": 355
              },
              "driving_side": "right",
              "intersections": [...]
            }
          ]
        }
      ]
    }
  ],
  "waypoints": [
    { "name": "Congress Avenue", "location": [-97.7431, 30.2672] },
    { "name": "Main Street", "location": [-96.7970, 32.7767] }
  ]
}

distance is in meters, duration in seconds. The geometry is an encoded polyline (Google’s format — most mapping libraries decode it natively). steps are the turn-by-turn instructions. The endpoint accepts up to 25 waypoints per request by default.

Useful endpoint variations:

Memory Requirements

The precomputed graph lives entirely in RAM (or in mmap’d files, which still need RAM to be useful). Rough numbers for the MLD algorithm on a car profile:

A 4 GB box handles most single-country or single-state use cases without breaking a sweat. If you’re running Texas car routing alongside a Nominatim geocoder on the same server, budget 4 GB for OSRM and another 3–4 GB for Nominatim, plus headroom for the OS. An 8–12 GB box handles both comfortably.

CH is slightly more memory-efficient than MLD because the shortcut graph is more compact, but the difference at regional scale is usually under 15%. Don’t choose your algorithm based on memory alone.

”But It’s Slower Than Google”

This comes up every time. The honest answer: for typical routing queries on a reasonably modern box, you’ll see end-to-end response times in the low-to-mid milliseconds — a bit more if the graph is large or the box is under load. Google is in the 100–300ms range for a round-trip API call, because that round-trip includes the internet.

If you’re calling OSRM on the same LAN, you’re almost certainly faster end-to-end than a commercial API. If you’re calling it from another continent on a slow VPS, you’re not. The latency is network-dominated once the routing itself takes under 10ms.

What OSRM legitimately doesn’t do as well as commercial APIs:

For anything where real-time conditions don’t matter — batch geocoding-adjacent work, logistics optimization, “find the closest five locations from this list,” delivery zone drawing — OSRM is genuinely better. Faster per-query, no per-request cost, no API key to rotate when it leaks.

Things That Will Bite You

Wrapping Up

One wget, four docker commands for the prep pipeline, one Compose file, and you have your own routing engine. No API key, no billing dashboard, no third party watching where your users are going.

The MLD vs CH choice is the one decision that matters most early on — pick MLD unless you know you have a stable profile and you need the extra query throughput. The osrm-customize step being fast is the whole reason MLD exists, and you will change your profile.

If you want the full self-hosted maps stack — geocoding plus routing plus tile serving — the Nominatim geocoding post from earlier this month is the natural companion to this one. Same OSM data, complementary services, same kind of “just run it yourself” energy.

Your 2 AM self will appreciate not having to explain a surprise routing API invoice to anyone.

Share this post on:
Share this post via WhatsApp Share this post on Facebook Share this post on X Share this post via Telegram Share this post on Pinterest Share this post via email

Send a Webmention

Written about this post on your own site? Send a webmention and it'll show up above once verified.

Next Post
Boundary vs Teleport

Discussion

Powered by Garrul . Sign in with GitHub or Google, or post anonymously.

Related Posts