trails/openspec/changes/self-hosting-guide/specs/self-hosting/spec.md at main

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.7 KiB

Raw Permalink Blame History

ADDED Requirements

Requirement: Minimal operator deployment example

The repository SHALL provide a self-contained example Docker Compose deployment (journal, planner, PostgreSQL/PostGIS, BRouter) configured via a plain env file, with healthchecks and pinned images, independent of the flagship infrastructure (no SOPS, no monitoring stack, single host).

Scenario: Fresh instance boots

WHEN an operator copies the example compose and .env.example, fills the required variables, and runs docker compose up
THEN all services become healthy and the journal and planner are reachable

Requirement: Documented environment contract

docs/self-hosting.md SHALL document every environment variable the apps read — required/optional, default, and description — plus reverse-proxy guidance, the BRouter segment-region decision, and BYO provider-credential setup (Wahoo and future providers) including redirect URIs.

Scenario: Env vars discoverable without reading code

WHEN an operator needs to configure SMTP or provider credentials
THEN the variable names, formats, and where to obtain values are in the guide

Scenario: Undocumented variable fails CI

WHEN a new variable is added to an app's .env.example without a guide entry
THEN the documentation check fails

Requirement: No default secrets, fail-fast on misconfiguration

The example deployment SHALL ship no working secret values (placeholders + generation commands only), and the journal SHALL refuse to start when a required secret is missing or still a placeholder, logging a message that links to the self-hosting guide.

Scenario: Placeholder secret blocks startup

WHEN an operator starts the journal with the .env.example placeholder secret unchanged
THEN the process exits with a clear error naming the variable and linking to the guide

Requirement: Upgrade and backup procedures

The guide SHALL document upgrading (image bump; schema migrations applied via the documented mechanism) and backup/restore: nightly PostgreSQL dump, media storage copy, and restore steps — including what not to back up (raw DB volume copies while running).

Scenario: Operator restores from backup

WHEN an operator follows the restore procedure with a dump + media copy
THEN the instance comes back with all user data intact

Requirement: CI-verified example deployment

CI SHALL boot the example compose (on changes to it, the guide, or app images, and on a weekly schedule), wait for health, and verify the journal health endpoint, a planner page load, and a BRouter route computation.

Scenario: Broken example blocks merge

WHEN an app change breaks the example deployment
THEN the smoke job fails on the PR

2.7 KiB Raw Permalink Blame History