freemoto/README.md

FreeMoto Web

A modern, mobile‑first motorcycle route planner. Backend in Go (proxy + static), frontend with Bootstrap + Leaflet, and Valhalla as the routing engine. Container‑ready with docker‑compose and CI for multi‑arch images.

Features

• Modern, mobile‑friendly UI (single tap on mobile, double‑click on desktop)
• Multi‑waypoint routing with draggable markers and reorder/remove list
• Round Trip planner
  • Distance target (km) and option to avoid repeated segments
  • Respects all routing options
• Rider controls
  • Twistiness slider (prefer curvy roads)
  • Highways preference slider (prefer faster highways)
  • Avoid: freeways, tolls, ferries, unpaved; Shortest route toggle
• Directions
  • Directions bottom sheet (collapsible, drag-to-resize)
  • Next‑maneuver banner; optional voice prompt
• Export GPX
  • Track (<trk>/<trkseg>/<trkpt>) and/or Route (<rte>/<rtept>)
  • OSMAnd‑friendly
• Theming and UX
  • Dracula‑style dark mode toggle with persistence
  • Summary pill (distance/time), floating actions, clean layout
• Performance
  • Gzip compression and strong caching for static assets
  • Small Alpine runtime image

Getting Started

Prerequisites

• Go (1.22+ recommended)
• Docker (for container builds)
• Valhalla routing backend
• Gitea (optional, for CI/CD and registry)

Configuration

Create a .env file in the project root:

VALHALLA_URL=http://valhalla:8002/route
PORT=8080
# Optional: Nominatim base URL (defaults to https://nominatim.openstreetmap.org)
NOMINATIM_URL=https://nominatim.openstreetmap.org
# Recommended: configure a descriptive User-Agent per Nominatim usage policy
# Example format: "AppName/Version (+contact-url-or-email)"
NOMINATIM_USER_AGENT=FreeMoto/1.0 (+https://fm.ztsw.de/)
# Optional: log level (debug, info, warn, error). Default: info
LOG_LEVEL=info

Local Development

cd app/web
go run main.go

Visit http://localhost:8080 in your browser.

Quick Start (docker-compose)

Build and run the web app alongside a Valhalla routing container with a single command. A docker-compose.yml is provided at the repository root.

1. Copy the example environment file and adjust values if needed:

cp .env.example .env

2. Start the stack:

docker compose up -d --build

3. Open the app:

http://localhost:8080

Notes:

• The web app will proxy /route to the valhalla service at http://valhalla:8002/route.
• You may mount custom_files/ into the Valhalla container (see docker-compose.yml) for tiles and custom configurations.

Docker

Build and run the container:

docker build -t freemoto-web .
docker run --env-file .env -p 8080:8080 freemoto-web

Docker Compose

Example docker-compose.yml:

services:
  freemoto-web:
    image: git.ztsw.de/pedan/freemoto/freemoto-web:latest
    ports:
      - "8080:8080"
    env_file:
      - .env
    #environment:
      # - VALHALLA_URL=http://10.200.0.15:8002/route
      # - PORT=8080
      # - NOMINATIM_URL=https://nominatim.openstreetmap.org
      # - NOMINATIM_USER_AGENT=FreeMoto/1.0 (+https://fm.ztsw.de/)
      # - LOG_LEVEL=debug
  valhalla-scripted:
    image: ghcr.io/valhalla/valhalla-scripted:latest
    ports:
        - 8002:8002
    volumes:
        - $PWD/custom_files:/custom_files
    environment:
        - tile_urls=https://download.geofabrik.de/europe/germany-latest.osm.pbf 

Alternatively, use the provided root-level docker-compose.yml for a local build of the web app and a Valhalla companion service, then run docker compose up -d --build.

Notes on Nominatim

• Please follow the official usage policy for Nominatim. Provide a meaningful NOMINATIM_USER_AGENT that includes a contact URL or email. The default is FreeMoto/1.0 (+https://fm.ztsw.de/).
• You can point NOMINATIM_URL to your own Nominatim instance or keep the default public endpoint.

Logging

• Configure verbosity with LOG_LEVEL.
  • Supported values: debug, info (default), warn, error.
• Incoming requests are logged at info level. Upstream success traces (Valhalla/Nominatim) are at debug. Errors are at error.

UI Overview

• Start/End fields with autocomplete and reverse geocoding
• Tap/double‑click to add waypoints; drag markers to adjust
• Waypoint list for reorder/remove
• Route Options include twistiness, highways, and avoid toggles
• Directions sheet (collapsible, draggable) + Next‑maneuver banner and optional voice
• Export GPX: Track/Route/Both

Performance

• Static assets are served with gzip (when supported) and strong caching
  • Cache-Control: public, max-age=31536000, immutable for /static
  • Short caching for index.html

Multi‑arch build and Registry

Build and push multi‑arch (amd64 + arm64) with Buildx:

# Login first (example)
docker login git.ztsw.de -u <user>

export IMAGE=git.ztsw.de/pedan/freemoto/freemoto-web
export TAG=latest
export TAG2=$(date +%Y%m%d-%H%M)

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t $IMAGE:$TAG \
  -t $IMAGE:$TAG2 \
  --push \
  .

CI: Gitea Actions

A workflow at .gitea/workflows/build-and-push.yml builds and pushes multi‑arch images on pushes and tags.

Configure repository secrets:

• CR_USERNAME – registry username
• CR_PASSWORD – registry token/password

Adjust env.IMAGE/env.REGISTRY in the workflow if you move the image.

Customization & Development

• Frontend
  • app/web/static/index.html – layout and controls
  • app/web/static/main.js – map init, theme, global controls
  • app/web/static/route.js – routing, waypoints, round trips, GPX
• Backend
  • app/web/main.go – static serving (gzip + caching), proxies /route, /geocode, /reverse

License

MIT