oixa/roadnik repository overview

⁠Roadnik

Roadnik is a privacy-friendly geolocation sharing system that lets you share your real-time location with others. The server and the built-in web map are fully self-hostable.

⁠Public instance

A ready-to-use instance is available at roadnik.app⁠ — no registration required. Download the Android app from Google Play⁠, open it, and it will generate a room key for you automatically.

The public instance is free to use. It has rate limits and storage quotas applied per room. No personal data is collected beyond the location points you choose to share.

⁠

⁠How it works

The server organizes location data into rooms. Each room is identified by a key that acts as a shared secret — anyone with the key can read and write location points to that room. Because a room can hold entries from multiple users (identified by a nickname), a single room is enough for a group ride, hike, or trip.

⁠Components

⁠Server

A .NET 10 application that stores geolocation points and serves the web map. Key features:

• Stores latitude, longitude, altitude, speed, bearing, accuracy, battery level, signal strength, and heart rate
• Per-room track storage with configurable point limits and age expiry
• Built-in interactive map (Vue 3 + Leaflet) with auto-centering on the selected user
• Map tile support: OpenStreetMap (no key required), Thunderforest (optional API key), and Strava heatmaps (requires token)
• Real-time updates
• Optional room registration for higher rate limits and point quotas (via API⁠ only)
• Optional Firebase Cloud Messaging (FCM) push notifications

⁠Android App

A .NET MAUI Android app (API 28+) that sends your location to roadnik.app in the background.
Features include:

• Built-in map with real-time location updates
• Uninterrupted background location reporting
• BLE heart rate monitor (HRM) support — pairs with any standard BLE HRM device and includes heart rate in each location report
• QR code room sharing
• Discord Rich Presence — while sharing is active, broadcasts approximate location, speed, and heart rate as a Discord activity with a direct link to the room

⁠Web Map

A Vue 3 / TypeScript SPA bundled with the server. It shows all tracks in a room on an interactive Leaflet map with auto-centering and live updates. Clicking a user's marker opens a popup with speed, battery, signal strength, and — when available — heart rate.

⁠Running the server

⁠Docker (recommended)

Multi-arch images (linux/amd64, linux/arm64) are published to Docker Hub⁠.

Example docker-compose.yml:

services:
  server:
    image: "oixa/roadnik:latest"
    restart: always
    ports:
      - "0.0.0.0:8080:8080/tcp"
    user: "1004:1004" # UID:GID of the roadnik user on the host
    environment:
      ROADNIK_WEBROOT: "/app/www"
      ROADNIK_LOG_DIR: "/var/roadnik/logs"
      ROADNIK_DATA_DIR: "/var/roadnik/data"
      ROADNIK_BIND_IP: "0.0.0.0"
      ROADNIK_BIND_PORT: "8080"
      ROADNIK_MAX_PATH_POINTS_PER_ROOM: "1000"
      ROADNIK_MAX_PATH_POINTS_AGE_HOURS: "720"
      ROADNIK_MIN_REPORT_INTERVAL: "9900" # ms
      ROADNIK_FIREBASE_JSON: "/var/roadnik/google_service_account.json"
      ROADNIK_FIREBASE_PROJECT_ID: "<your-firebase-project-id>"
      ROADNIK_TF_API_KEY: "<your-thunderforest-api-key>"       # optional
      ROADNIK_MAP_TILES_CACHE_SIZE: "10737418240"              # optional, bytes
      ROADNIK_ADMIN_API_KEY: "<your-admin-api-key>"            # optional
      ROADNIK_STRAVA_SESSION: "<your-strava-session-cookie>"   # optional
    volumes:
      - /home/roadnik:/var/roadnik
    tty: true

⁠Configuration

All settings are passed via environment variables.

Required:

Optional:

⁠Behind NGINX

location / {
    proxy_pass http://127.0.0.1:8080/;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    proxy_http_version 1.1;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}