osrm-frontend

This is the frontend served at https://map.project-osrm.org. This frontend builds heavily on top of Leaflet Routing Machine. If you need a simple OSRM integration in your webpage, you should start from there.

Using Docker

The easiest and quickest way to setup your own routing engine backend is to use Docker images we provide. We base our Docker images on Alpine Linux and make sure they are as lightweight as possible.

Serves the frontend at http://localhost:9966 running queries against the routing engine backend:

docker run -p 9966:9966 ghcr.io/project-osrm/osrm-frontend:latest

By default Docker uses a single routing profile named default and sends requests to http://localhost:5000.

Recommended: multiple profiles with OSRM_MODES

OSRM_MODES is the current Docker runtime configuration interface. It accepts a JSON array of objects with name and url fields.

docker run -p 9966:9966 \
  -e 'OSRM_MODES=[{"name":"car","url":"https://routing.openstreetmap.de/routed-car"},{"name":"foot","url":"https://routing.openstreetmap.de/routed-foot"},{"name":"bike","url":"https://routing.openstreetmap.de/routed-bike"}]' \
  ghcr.io/project-osrm/osrm-frontend:latest

Deprecated: single backend with OSRM_BACKEND

OSRM_BACKEND is deprecated. It is still supported for backward compatibility and configures exactly one backend named default.

docker run -p 9966:9966 \
  -e OSRM_BACKEND='http://localhost:5001' \
  ghcr.io/project-osrm/osrm-frontend:latest

Precedence

1. If only OSRM_BACKEND is set, the frontend configures one backend and emits a deprecation warning.
2. If only OSRM_MODES is set, the frontend parses the JSON and configures the listed modes.
3. If both are set, OSRM_MODES wins and the frontend emits a deprecation warning for OSRM_BACKEND.

In case Docker complains about not being able to connect to the Docker daemon make sure you are in the docker group.

sudo usermod -aG docker $USER

To build the docker image locally:

docker build -f docker/Dockerfile -t osrm-frontend .
docker run -p 9966:9966 osrm-frontend

Development

Install dependencies via

npm install

Then compile assets and start the local server with

npm start

On Windows with no Unix tools installed (bash and cp) the server could be started with two other commands executed by npm start internally:

npm run compile
npm run start-index

Changing Backends

For Docker deployments, prefer runtime configuration via OSRM_MODES (see above) instead of editing source files. If you need source-level customization, edit the parseModes() and buildServices() functions in src/leaflet_options.js.

Customizing Tile Layers and Overlays

Base layers (layer)

The layer property in src/leaflet_options.js defines the base tile layers shown as radio buttons in the map's layer control (bottom-left corner).

Default base layers:

Label	Source	Max zoom
Streets	CartoDB Voyager	19
Outdoors	OpenTopoMap	17
Satellite	ESRI World Imagery	19
openstreetmap.org	OSM	19
openstreetmap.de	OSM.de	19

Changing the default layer for Docker deployments: Set OSRM_DEFAULT_LAYER to one of: streets, outdoors, satellite, osm, osm_de.

docker run -p 9966:9966 -e OSRM_DEFAULT_LAYER=satellite ghcr.io/project-osrm/osrm-frontend:latest

Adding or replacing base layers (source builds): Define a new L.tileLayer and add it to the layer array in src/leaflet_options.js:

var myTiles = L.tileLayer('https://example.com/tiles/{z}/{x}/{y}.png', {
    attribution: '© My Tile Provider',
    maxZoom: 18
});

// In the leafletOptions object:
layer: [{
    'My Custom Map': myTiles,
    'Streets': streets,
    'Outdoors': outdoors,
    // ... other layers
}]

Overlays (overlay)

Overlays are toggleable tile layers rendered on top of the base layer. They appear as checkboxes in the layer control.

Overlay	Source	Description
Hiking	Waymarked Trails	Hiking routes overlay (CC-BY-SA)
Bike	Waymarked Trails	Cycling routes overlay (CC-BY-SA). Auto-activated when a bike profile is selected.
Small Components	GeoFabrik OSM Inspector	Debug overlay highlighting small disconnected road segments. Useful for checking OSM data quality.

The user's overlay preference is saved in localStorage and restored on reload.

Adding custom overlays: Define a L.tileLayer and add an entry to the overlay object in src/leaflet_options.js:

overlay: {
    'Hiking': hiking,
    'Bike': bike,
    'Small Components': small_components,
    'My Overlay': L.tileLayer('https://example.com/overlay/{z}/{x}/{y}.png', {})
}

For debug tiles showing speeds and small components available at /debug adjust in debug/index.html

"osrm": {
  "type": "vector",
  "tiles" : ["http://localhost:5000/tile/v1/car/tile({x},{y},{z}).mvt"]
}