BBergleandClaude Sonnet 5
5d4d76203f
Phase 0 deployment: three-service docker-compose.yml (caddy, api, db), a Caddyfile that proxies /api/* to the api service and serves the SPA with index.html fallback, and two Gitea Actions workflows (release.yml builds and pushes both images on a v* tag or manual dispatch; deploy.yml is manual-only and rolls them out to the Unraid host). The non-obvious part is the Docker-outside-of-Docker constraint on this act_runner setup: job containers share the host's Docker daemon over the socket but do NOT share its filesystem, so any command whose correctness depends on a client-side local path (docker cp to a host path, mv/rm -rf on a host path, a bind-mount source path on a `docker run` command line issued from inside a job) silently operates on the ephemeral job container's own throwaway filesystem instead. Two things are safe: a bind mount declared in a compose file's `volumes:` block (resolved by the daemon when `docker compose up` creates the service — this is why db's pgdata bind mount is fine), and a named volume populated by a one-shot `docker run` whose *command* does the copying (this is why the web image's static build output goes into a `web_build` named volume via `docker run -v ... sh -c 'cp -a ...'` in deploy.yml, rather than any `docker cp`). Local verification (see PR description for full detail) caught a real bug: `docker compose run api alembic upgrade head` needs VELODROME_DB_APP_PASSWORD/VELODROME_DB_AUTH_PASSWORD as container env vars to create the two runtime roles, but --env-file alone doesn't inject them since the api service's permanent environment block deliberately omits them (least-privilege — the long-running app should never need role-creation passwords). Fixed by passing them as explicit -e overrides on the migration step, same as VELODROME_DATABASE_URL_MIGRATE. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
bike-app
A self-hosted cycling app: syncs rides from a Bryton Rider 650, tracks mileage like Strava, and adds a spare-parts inventory and a maintenance record with mileage-milestone reminders.
Status: planning complete, no code written yet.
Why
Today the Rider 650 syncs over Bluetooth to the Bryton Active phone app, which forwards to Strava — but Active has no background sync, so you have to remember to open the app. Research found a better path that removes the phone entirely:
ride ends -> Rider 650 joins home Wi-Fi (Main Menu -> Data Sync)
-> uploads to Bryton cloud
-> this app's poller fetches the ORIGINAL FIT file
-> rides, wear tracking, and push reminders
That's also higher fidelity than the current route — Strava's API can only ever return smoothed streams, never the original file.
Docs
| File | What's in it |
|---|---|
docs/PLAN.md |
The full implementation plan: stack, schema, ingestion pipeline, auth, notifications, phased roadmap, CI/CD, risks, verification |
docs/RESEARCH.md |
Raw findings: the Bryton cloud protocol (endpoints, headers, auth), FIT library comparisons, maintenance interval tables, self-hostable geo services, Gitea Actions gotchas |
docs/DECISIONS.md |
Every decision taken, what was rejected, and why |
Planned stack
Python 3.12 / FastAPI / SQLAlchemy async / PostgreSQL 16 + PostGIS, procrastinate for jobs,
SvelteKit static SPA as an installable PWA, MapLibre GL, all behind Caddy in Docker Compose.
Source control and CI in self-hosted Gitea with an act_runner on the same box.
Four containers in v1, under 2GB RAM.
Next steps
- Verify on the Rider 650: does
Main Menu -> Data Syncupload automatically on joining Wi-Fi, or only on manual trigger? This determines how completely the phone leaves the loop. - Plug the 650 in over USB and
ls -Rthe mounted volume to confirm the real.fitpath (documented asBryton/Activities/, but worth confirming). - Grab a real
.fitfile from it and run it throughfitdecode— Bryton's encoder is not Garmin's, and the schema should be checked against reality before it's written. - Then Phase 0: scaffolding and CI (see the roadmap in
docs/PLAN.md).