trails-cool/trails
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
trails/openspec/changes/self-hosting-guide/tasks.md
Ullrich Schäfer 5dd4968626 docs+openspec: prior-art research (Organic Maps, Endurain, wanderer) and 15 proposals 
Add docs/inspirations.md as the durable record of the 2026-07-05/06
prior-art research — per-project learnings with source paths, canonical
credit lines, and the changes each spawned — and extend the
acknowledgment lists in philosophy.md/architecture.md (Organic Maps,
Endurain, wanderer).

New OpenSpec changes (proposal/design/specs/tasks each):
- Organic Maps: elevation-profile-hardening, gpx-parser-robustness,
  hiking-time-estimate, poi-index, hiking-foot-profile
- Endurain: account-export, activity-duplicate-review,
  fit-parsing-hardening, activity-locations, self-hosting-guide,
  activity-privacy-controls
- wanderer: federation-hardening, link-share-tokens
- credits-page (user-visible acknowledgments)

Updated in-flight changes with wanderer prior-art sections:
route-federation, route-discovery.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-06 07:23:00 +02:00

2.2 KiB
Raw Blame History

1. Env audit

  • 1.1 Enumerate every env variable read by journal, planner, db, jobs (grep process.env + .env.examples); classify required/optional/default; fix any default that assumes flagship values (domains, internal IPs)
  • 1.2 Draft the env reference table from the audit

2. Example deployment

  • 2.1 Write infrastructure/examples/docker-compose.selfhost.yml (journal, planner, postgres+postgis, brouter; healthchecks; named volumes; pinned tags) + infrastructure/examples/.env.example
  • 2.2 Verify from scratch on a clean machine/VM: fill env, up, create account, plan a route, save to journal
  • 2.3 Document the Docker file-based-secrets variant inline (DB password, app secrets)
  • 2.4 Ensure example compose + .env.example contain placeholders and generation commands only (openssl rand -hex 32), never working secret values
  • 2.5 Add a boot-time check to the journal: refuse to start when a required secret is missing or a known placeholder, with a log line linking to the self-hosting guide; unit test both paths

3. Guide

  • 3.1 Write docs/self-hosting.md: prerequisites, quick start, env table, reverse proxy (Caddy example), BRouter segment-region choice, BYO provider credentials (Wahoo redirect URI + HTTPS requirement), upgrade procedure, backup & restore, optional POI index note (per poi-index change), scaling/limits
  • 3.1b Backup section: enumerate backup targets (pg_dump + media) vs rebuildable-and-excluded state (BRouter segments, POI index, monitoring data); state the restore-version rule (restore into the producing app version, then upgrade)
  • 3.2 Link from README and docs/architecture.md; note the flagship docs (docs/deployment.md) are the reference production deployment, not the operator path

4. CI

  • 4.1 Add a compose smoke workflow: boot example with generated env, wait healthy, curl journal health + planner page, request a BRouter route with the CI segment; trigger on example/guide/Dockerfile changes + weekly cron
  • 4.2 Add the docs-drift check: every .env.example variable must appear in the guide's table

5. Verification

  • 5.1 Run pnpm typecheck && pnpm lint && pnpm test (unchanged app code paths) and the new smoke workflow on the PR