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](https://golang.org/) (1.22+ recommended)
- [Docker](https://www.docker.com/) (for container builds)
- [Valhalla](https://github.com/valhalla/valhalla) routing backend
- [Gitea](https://gitea.io/) (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

```bash
cd app/web
go run main.go
```

Visit [http://localhost:8080](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:

```bash
cp .env.example .env
```

2. Start the stack:

```bash
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:

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

### Docker Compose

Example `docker-compose.yml`:

```yaml
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:

```bash
# 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