Route-planning app for cyclists, runners, and hikers. Interactive map editor, GPX import/export, and a personal route library. Open source, self-hostable, and also available as a hosted service.
📚 Full documentation: docs.routess.com
git clone https://github.com/robbeverhelst/routess.git
cd routess
cp docker/.env.selfhost.example .env
# fill in JWT_SECRET, GOOGLE_CLIENT_ID/SECRET, VITE_MAPBOX_ACCESS_TOKEN
docker compose -f docker/compose.selfhost.yaml --project-directory . up -dThen open http://localhost:8080.
See docs/operations/self-host for the full walkthrough (OAuth setup, optional services, Helm/Kubernetes path, TLS).
Minimum to run routess:
- A Google OAuth client (the only login provider today)
- A Mapbox access token (free tier is fine)
- A JWT secret (any long random string)
Optional services degrade gracefully when unset: Resend (email), Stadia Maps (surface analysis), Sentry/GlitchTip (error reporting), Umami (product analytics), Prometheus (metrics).
bun install
cp .env.example .env
bun devDefaults: web :5173, API :3000, docs :3001, Postgres :5432, pgAdmin :5050. Ports auto-shift if taken. Full dev guide: docs/getting-started/local-setup.
bun run lint # biome check
bun run check-types # tsc across all workspaces
bun run test # all tests
bun run ci # full pipeline (postgres + format:check + lint + check-types + build + test)Run bun run with no arguments to list every script.
routess/
├── apps/
│ ├── web/ # React + Vite + Tailwind + Mapbox
│ ├── api/ # NestJS + PostgreSQL + MikroORM
│ ├── cli/ # `routess` CLI (npm)
│ └── docs/ # Next.js (Fumadocs)
├── packages/
│ ├── core/ # @routess/core — shared business logic & state
│ ├── api-client/ # @routess/api-client — type-safe API client
│ ├── i18n/ # @routess/i18n — internationalization
│ └── design-tokens/ # @routess/design-tokens — design system
├── charts/routess/ # Helm chart
└── docker/ # buildx bake + dev/self-host compose files
| Layer | Technology |
|---|---|
| Frontend | React, TypeScript, Vite, Tailwind, Mapbox GL |
| Backend | NestJS, PostgreSQL, MikroORM, OpenTelemetry |
| Docs | Next.js, Fumadocs |
| Build | Bun workspaces, Biome, Docker Buildx Bake |
| Deploy | Helm, Kubernetes, GitHub Actions, semantic-release |
PRs welcome. See CONTRIBUTING.md for the short version and docs/contributing for depth. Run bun run ci before submitting; CI enforces production-strict TypeScript and Biome rules.
Security issues: please follow SECURITY.md — do not open public issues for vulnerabilities.
MIT © Robbe Verhelst.