A server is one Docker container. It serves the browser client, the routes and
the WebSocket game on one port (8080 inside the container). TLS belongs to a
reverse proxy in front of it: browsers only allow Bluetooth on https:// pages.
git clone <your-repo-url> openradlr && cd openradlr
make setup # creates .env from .env.example; later runs add new settings
$EDITOR .env
make upSettings for production in .env:
OPENRADLR_SERVER_NAME=Leon's Ride Club
OPENRADLR_PUBLIC_URL=https://ride.example.org
OPENRADLR_TRUST_PROXY=true # client IPs from X-Forwarded-For (per-IP limit)
OPENRADLR_MAX_PLAYERS=50 # trainer riders at the same time, all routes together
OPENRADLR_MAX_PADDLE_PLAYERS=20 # phone riders, in seats of their own
OPENRADLR_MAX_VISIBLE_RIDERS=200 # riders per state message, humans first
OPENRADLR_ALLOW_SIMULATED_TRAINER=false # only real trainers on the start screen
OPENRADLR_ALLOW_PADDLE_MODE=true # phone paddles (marked 📱, no Strava, no ride files)
OPENRADLR_PRIVACY_URL=https://ride.example.org/privacy/ # your privacy policy, linked in the start menu
OPENRADLR_ANALYTICS_DOMAIN= # optional Plausible analytics, off when empty (see .env.example)
# OPENRADLR_OBN_URL=wss://obn.example/v0 # optional: share the tracks with other apps (see OpenBikeNet below)
OPENRADLR_HTTP_BIND=127.0.0.1 # only the proxy on this machine can reach it
OPENRADLR_HTTP_PORT=8080
COMPOSE_PROFILES= # leave the bundled Caddy offOPENRADLR_PUBLIC_URL also becomes the only page origin allowed to open game
connections (OPENRADLR_ALLOWED_ORIGINS in docker-compose.yml). Without it,
any web page may open a game connection to your server, which is fine on a
home network but not for a public server: always set it there. Only set
OPENRADLR_TRUST_PROXY=true when the proxy is the only way in, otherwise
anyone could fake their address in the header.
Deploy new commits later with make update (git pull, rebuild, restart,
wait until healthy).
make update, make restart and make down drop everyone who is riding, so
they first ask the running server who is on it. With riders connected you get
the count and where they ride, and a prompt that defaults to No (nothing is
pulled or changed then). Without a terminal (cron, CI, ssh without a TTY) they
refuse instead of waiting; add FORCE=1 (make update FORCE=1) to go ahead
regardless. If no server is running or it does not answer, they continue.
Caddy proxies WebSockets and sets X-Forwarded-For on its own. The server
compresses its responses itself (Brotli or gzip); encode leaves those as they
are and only matters for anything else the proxy serves:
ride.example.org {
encode zstd gzip
reverse_proxy 127.0.0.1:8080
}Put both containers on a shared Docker network instead of publishing a port.
Next to docker-compose.yml create docker-compose.override.yml (Compose
reads it automatically; it is not in git):
services:
server:
ports: !reset []
networks: [default, proxy]
networks:
proxy:
external: true
name: caddy # the network your Caddy container is onand point Caddy at the container name:
ride.example.org {
encode zstd gzip
reverse_proxy openradlr-server-1:8080
}The official server splits into two addresses: a static landing page on the
main domain (openradlr.com, from landing/) and the app on a subdomain
(app.openradlr.com). Both run in the same Compose stack. Self-hosters who
don't want a landing page leave this out; nothing changes for them.
-
DNS:
A/AAAArecords for the bare domain,wwwandapp, all to the server. -
.env:COMPOSE_PROFILES=tls,landing OPENRADLR_DOMAIN=app.openradlr.com OPENRADLR_PUBLIC_URL=https://app.openradlr.com OPENRADLR_LANDING_DOMAIN=openradlr.com, www.openradlr.com OPENRADLR_LANDING_URL=https://openradlr.com OPENRADLR_LANDING_PLAUSIBLE_DOMAIN=openradlr.com # optional, cookie-free analytics # OPENRADLR_DISCORD_URL=https://discord.gg/your-invite # optional, community link in app + landing # OPENRADLR_PRIVACY_URL=https://... # optional, privacy link (start menu + landing footer) # OPENRADLR_LANDING_IMPRINT_URL=https://... # optional, imprint link in the footer
-
make up. The bundled Caddy serves the landing page on the bare domain, redirectswww.to it and proxies the app subdomain as before. SetOPENRADLR_DISCORD_URLto your community's invite, configured in Discord to never expire with unlimited uses. The same setting supplies the app start menu (through/api/info) and the landing page (PUBLIC_DISCORD_URL). Leave it empty to hide the app link and show the landing page's GitHub fallback. Changing it requires recreating the server container and rebuilding the static landing page, not a source change or release:make upapplies both. -
Strava: the Authorization Callback Domain in the Strava API settings must be the app subdomain (
app.openradlr.com). Change it when moving the app, then check Connect with Strava once.
Behind your own Caddy, leave tls out of COMPOSE_PROFILES; the landing
container is published on 127.0.0.1:8081 (OPENRADLR_LANDING_PORT):
openradlr.com {
encode zstd gzip
reverse_proxy 127.0.0.1:8081
}
www.openradlr.com {
redir https://openradlr.com{uri} permanent
}
app.openradlr.com {
encode zstd gzip
reverse_proxy 127.0.0.1:8080
}The page's links are baked in at build time from .env, so run make up
again after changing them. Details: landing/README.md.
-
Create an API application at https://www.strava.com/settings/api. Authorization Callback Domain: the host of your public URL, e.g.
ride.example.org. -
In
.env:OPENRADLR_STRAVA_CLIENT_ID=12345 OPENRADLR_STRAVA_CLIENT_SECRET=… OPENRADLR_REQUIRE_STRAVA=false # true: riders must connect Strava to ride OPENRADLR_SECRET_KEY=… # openssl rand -hex 32; keeps logins across updates
-
make up.
To try it locally, copy .env.dev.example to .env.dev and run make dev
(see the comments in that file). Strava accepts localhost and 127.0.0.1 as
callback domains, so the same Strava app works locally. Open the app at
http://localhost:8080 (the OPENRADLR_PUBLIC_URL in that file).
Riders then see Connect with Strava on the start screen. After a ride,
Finish ride offers Upload to Strava (and .tcx, .gpx and .fit downloads either way).
Strava gets a FIT file marked as a virtual ride (sub_sport virtual activity):
Strava files it as a Virtual Ride and keeps the ride's own elevation. Its
elevation map would see open sea there and drop the climbing, as it did for
the TCX uploads before.
With OPENRADLR_REQUIRE_STRAVA=true every rider needs a real Strava account,
and one account can ride only once at a time — a simple hurdle against bots
and scripts.
Strava logins are saved in a SQLite database on the data Docker volume
(/app/data), so riders stay connected through make update and restarts.
Session ids are stored only as hashes and refresh tokens are encrypted with
OPENRADLR_SECRET_KEY, which must stay the same across deploys (changing it
logs everyone out once, which is harmless). Without the key logins stay in
memory and are lost on every restart. Back the volume up like any data:
docker run --rm -v openradlr_data:/data -v "$PWD":/backup alpine tar czf /backup/openradlr-data.tgz -C /data .The start menu also shows how far everyone has ridden on the server, on
trainers and on phones. Only the two kilometre totals are kept, in stats.json
next to the database (set OPENRADLR_STATS_FILE to put it elsewhere); without a
data directory they restart from zero. Riders declare their own device, so the
numbers are for fun, not a leaderboard.
Things to know:
- Sessions are kept in memory. After a restart riders press Connect again; Strava skips its consent screen the second time.
- A new Strava API app may be limited to a single athlete until Strava approves it for more ("athlete capacity" in the API settings).
- Uploads carry GPS positions in a virtual world off Mallorca (see routes), so Strava shows a map. Once Strava has processed an upload, the server sets the sport type to Virtual Ride, which keeps it off real-world segments.
Set OPENRADLR_OBN_URL (a ws:// or wss:// URL of an OpenBikeNet server) to share the
tracks (routes with openbikenet, such as the velodrome) with riders of other apps. The server
then sends the name, position, speed, power and cadence of the riders on those tracks, and shows
the riders of other apps to everyone in the world (the tracks have no bots). One connection
serves all tracks. Empty or unset = not connected; nothing is sent. If the connection
drops, the other apps' riders vanish and the server reconnects with a growing pause (1 s up to
a minute). /api/info marks the route with "shared": true while the link is configured.
- Riders doing a workout, riders off the route and bots are never sent.
- A rider of another app that is silent for 10 s is hidden until they send again.
- A server that stays silent for 20 s gets a ping; after 10 s more without an answer the connection counts as dropped and is reopened.
ws://is unencrypted: rider names and values cross the network in the clear. Usewss://whenever the OpenBikeNet server is not on your own machine or network.
| Setting | Default | What it limits |
|---|---|---|
OPENRADLR_MAX_PLAYERS |
50 | Trainer riders at the same time across all routes (phone riders not counted) |
OPENRADLR_MAX_PADDLE_PLAYERS |
20 | Phone-paddle riders at the same time, in seats of their own so they never block a trainer rider |
OPENRADLR_MAX_VISIBLE_RIDERS |
200 | Riders in one state message; humans first, then the nearest bots |
OPENRADLR_MAX_CONNECTIONS_PER_IP |
4 | Open game connections per IP (needs OPENRADLR_TRUST_PROXY behind a proxy) |
OPENRADLR_MESSAGES_PER_SECOND |
20 | Messages per connection (the client sends about 4); floods are dropped, then the connection is closed |
OPENRADLR_ALLOWED_ORIGINS |
the public URL | Pages from other sites can't open game connections |
OPENRADLR_REQUIRE_STRAVA |
false | Riders need a Strava account; one ride per account |
OPENRADLR_GRACE_S |
60 | How long a rider whose connection dropped is kept (coasting, holding their place) before being removed; 0 removes at once |
OPENRADLR_AFK_TIMEOUT_S |
1800 | Seconds of 0 W before a "Still riding?" warning; an unanswered warning removes the rider. 0 turns it off |
OPENRADLR_AFK_REMINDER_S |
600 | Seconds of 0 W after "Stay" before the next warning |
Connections must say hello and join within 15 s, and silent connections are closed after 120 s. Chat is limited to bursts of 5, then one message every 2 s. Trainer data is still trusted (watts are only clamped to 2500 W); this is about keeping a small community server usable, not about stopping a determined cheater.
Every *.json file in routes/ becomes a world riders can pick on the start
screen; OPENRADLR_ROUTE is the default and listed first. Routes are mounted
read-only, so a new file only needs make restart. See routes.
For a server without a reverse proxy, the bundled Caddy can handle TLS:
COMPOSE_PROFILES=tls and OPENRADLR_DOMAIN=ride.example.org in .env
(ports 80 and 443 must be reachable).
The private /internal/metrics endpoint also exports
openradlr_client_requests_total{client,app_version,app_build}. This aggregate
counter helps compare native app releases and diagnose release-specific issues.
It counts successful GET /api/info responses, excluding static assets, health
checks and scrapes; menu refreshes count again. It does not estimate unique
people or sessions. Set OPENRADLR_APP_METRIC_RELEASES to a comma-separated
allowlist such as android/0.1.0/3,ios/1.0/1 when supporting additional releases. See App release information
for label limits, compatibility with older app builds and example PromQL.