9d4c7d2b41
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>
53 lines
2.4 KiB
Markdown
53 lines
2.4 KiB
Markdown
## 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
|