trails-cool/trails
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
trails/openspec/specs/local-dev-environment/spec.md
Ullrich Schäfer 9d4c7d2b41
Archive staging-environments change; update local-dev spec 
Staging environments are live and fully operational. Marks the remaining
verification tasks complete, syncs the delta spec to main specs, and
archives the change.

Also adds a "When to Use Local vs. Staging" reference table to the
local-dev-environment spec so the boundary between the two environments
is documented in one place.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-17 20:38:07 +02:00

2.4 KiB
Raw Blame History

Purpose

One-command local development setup with PostgreSQL, BRouter, automatic schema migration, and segment downloading.

When to Use Local vs. Staging

Scenario Use
Everyday development, unit tests, E2E tests Local (pnpm dev:full)
Sharing a work-in-progress with reviewers PR preview (pr-<N>.staging.trails.cool)
Testing against production-like infra (Caddy TLS, Docker networking) Staging (staging.trails.cool)
Wahoo OAuth callback testing Local with HTTPS=1 (see CLAUDE.md)
ActivityPub federation testing Staging (requires real HTTPS + public domain)

The Planner, Journal, PostgreSQL, and BRouter all run locally. The local stack is the default for all development work. Staging is not a replacement for local dev — it is a pre-merge verification surface and a way to share work without merging first.

Requirements

Requirement: One-command dev startup

The project SHALL provide a single command that starts all services needed for local development.

Scenario: Start full dev stack

  • WHEN a developer runs pnpm dev:full
  • THEN PostgreSQL, BRouter, and both apps start and are reachable at their respective ports

Scenario: Services are healthy before apps start

  • WHEN the dev script starts
  • THEN it waits for PostgreSQL health check and BRouter readiness before starting the apps

Requirement: Automatic database setup

The dev environment SHALL automatically create schemas and tables on startup.

Scenario: First run database setup

  • WHEN pnpm dev:full runs for the first time
  • THEN the planner and journal PostgreSQL schemas and tables are created automatically

Requirement: BRouter segment for local testing

The dev environment SHALL include at least one BRouter segment for route computation testing.

Scenario: Download segment on first run

  • WHEN the BRouter Docker volume has no segments
  • THEN the dev script downloads E10_N50.rd5 (Berlin area, ~124MB)

Scenario: Skip download if segment exists

  • WHEN the BRouter Docker volume already has segments
  • THEN the dev script skips the download

Requirement: Local route computation

The Planner SHALL be able to compute routes locally in the dev environment.

Scenario: Compute a route in Berlin

  • WHEN a developer sends a route request with two Berlin waypoints to the local Planner
  • THEN the Planner proxies to local BRouter and returns a valid GeoJSON route