rippr/docs/v3/V3-17-osrm-hosting.md

V3-17 — Self-hosted OSRM: investigate and stand one up

Phase Infrastructure · Depends on nothing · Size M · Blocks V3-08, V3-09 · Status Not started

Goal

Get a self-hosted OSRM instance running somewhere, so V3-08 (road-snapped routing and ETA) has a real backend to build against instead of a deferred decision.

Context

V3-08 named the choice of routing engine as "a decision that cannot be deferred," and the conversation that spawned this ticket picked a direction without picking a provider: self-hosted OSRM, over a hosted API (GraphHopper, Mapbox Directions) or the public OSRM demo (explicitly not for production use).

This ticket exists because that decision itself has a wrinkle worth naming up front: this whole v3 backlog's organizing principle, stated in docs/BACKLOG.md, is "v3 is everything that can be built with no server. v4 is everything that cannot." A self-hosted OSRM instance is a server. Strictly, that makes V3-08 and V3-09 — anything that depends on this ticket — v4 work by the project's own definition, not v3, even though they're filed under docs/v3/ today and the routing itself has nothing to do with the group-rides/accounts/backup programme that currently defines v4. Whether to formally renumber them is a documentation decision for whoever picks this up next; this ticket does not resolve it, only flags it so it isn't silently glossed over.

Design

Two separable questions:

1. Where does it run? A small VPS (the same shape of box that would eventually host the v4 group-ride server, so this could double as an early step toward that) versus something serverless/managed. OSRM's own Docker image is the standard path either way.
2. What data does it need? A regional OSM extract, not the planet — start with whatever region actually gets ridden (per docs/LAUNCH.md, this is presently a friends-and-family app, so the region is small and known). Geofabrik publishes regional .osm.pbf extracts sized for exactly this.

Profiles matter for this app specifically (see V3-08's Design section): a motorcycle route and a bicycle route between the same two pins should genuinely differ. OSRM ships car/bike/foot profiles out of the box; a motorcycle profile is closer to car (mostly avoids the walk-only restrictions bike profiles impose) but might want the twisty-road preference a stock car profile doesn't have reason to express. Confirming that is part of this ticket's investigation, not something to guess at now.

Implementation

1. Pick and provision a host (see Design's first question)
2. Download and preprocess a regional extract with OSRM's own toolchain (osrm-extract → osrm-partition → osrm-customize, or the older osrm-contract pipeline depending on the OSRM version chosen)
3. Run osrm-routed behind whatever the host offers for TLS termination — the app will be calling this over the public internet from riders' phones, so plain HTTP is not an option
4. Confirm at least a car-equivalent and a bike profile both return sane routes for a handful of real local pin pairs, by hand, before writing any app code against it
5. Write the resulting base URL and auth (if any) down for V3-08 to consume — as configuration, never a hardcoded value, matching V3-08's own "no API key committed to the repository" acceptance criterion, which applies here too even though there's no third-party vendor to protect a key from — an open, unauthenticated routing endpoint is still worth not publishing in a public repo
6. A basic uptime check of some kind — this becomes a real dependency the app relies on, not a fire-and-forget script

Acceptance criteria

• An OSRM instance is reachable over HTTPS from outside the host network
• Returns a road-following route for a real pin pair in the region actually ridden
• At least two distinct profiles (car-equivalent, bike) both work
• The endpoint and any credentials live in configuration, not source
• Documented: what's running, where, how to update the extract when it goes stale, and what it costs (if anything) to keep running

Tests

Infrastructure, not app code — no flutter test coverage belongs to this ticket directly. V3-08's own FakeRoutingService-driven tests are what verify the app's behavior; this ticket's job is only to make the real thing exist for that fake to stand in for.

Risks

• Ongoing hosting cost and maintenance, however small — this is the first piece of always-on infrastructure this project has taken on. Worth being honest that "no server" stopped being true the moment this ticket is picked up, regardless of which numbering bucket it ends up filed under.
• OSM extracts go stale. A road that didn't exist at extract time won't route. Needs a refresh cadence, not a one-time setup.
• Regional extracts are cheap; do not reach for a planet-wide extract preemptively.

Out of scope

Actually building V3-08/V3-09 against this once it exists — that's their ticket, not this one. Turn-by-turn navigation, traffic-aware routing, anything beyond what stock OSRM gives you.