0cf87b72ab
- authentication-methods: document completeAuth mode param ("redirect"|"json");
clarify add-passkey nudge (no dismiss mechanism, disappears on passkey add)
- journal-auth: session maxAge is 30 days; terms allow-list uses /legal/ prefix
matching (broader than fixed list of paths)
- session-notes: mark awareness isolation and UndoManager isolation as not yet
implemented (shared instances in current code)
- activity-feed: add fan-out scenario for visibility change to public
- explore: note that ?perPage is not yet implemented (hardcoded page size)
- multi-day-routes: add per-day GPX track split scenario (splitByDays option);
document overnight vs isDayBreak naming gap
- osm-poi-overlays: debounce is 800ms + 2000ms min interval (not 500ms);
retry is not automatic (fires on next viewport change)
- brouter-integration: rate limit corrected to 300/hour; add segment-cache
requirement (client caches per-pair segments)
- wahoo-route-push: OAuth state shape uses camelCase (returnTo, pushAfter
object) not snake_case with push_after boolean
- komoot-import: document noop adapter / ConnectedServiceManager bypass;
note four Komoot-specific routes that bypass the generic OAuth framework
- background-jobs: exponential backoff not wired (retryLimit only); add SIGINT
- connected-services: add revoked status; name ConnectionNotActiveError
- infrastructure: add INTEGRATION_SECRET and SENTRY_DSN to env var lists;
split secret decryption scenario by workflow (cd-apps vs cd-infra)
- secret-management: correct CD decryption — cd-apps only decrypts app.env;
cd-infra decrypts both
- transactional-emails: welcome email is async (pg-boss job); magic-link email
includes 6-digit numeric code
- journal-route-detail: websites are https: links (not mailto:); opening_hours
is also displayed
- local-dev-environment: add mobile app (Expo) dev commands
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
194 lines
9.7 KiB
Markdown
194 lines
9.7 KiB
Markdown
## Purpose
|
|
|
|
Server provisioning on Hetzner, Docker Compose deployment, CI/CD pipelines, database and BRouter management, TLS, Sentry, Grafana, and monitoring stack for the flagship instance.
|
|
## Requirements
|
|
### Requirement: Terraform Hetzner provisioning
|
|
Infrastructure SHALL be provisioned on Hetzner Cloud using Terraform with the Hetzner provider.
|
|
|
|
#### Scenario: Provision server
|
|
- **WHEN** `terraform apply` is run
|
|
- **THEN** a Hetzner cx23 server (2 vCPU, 4 GB RAM, 40 GB SSD) is created with Docker installed
|
|
|
|
### Requirement: Docker Compose deployment
|
|
All services SHALL be deployed via Docker Compose, including Grafana, Prometheus, and Loki for the flagship instance.
|
|
|
|
#### Scenario: Monitoring stack starts
|
|
- **WHEN** `docker compose up -d` is run
|
|
- **THEN** Grafana, Prometheus, Loki, Promtail, postgres-exporter, node-exporter, and cAdvisor containers start alongside the application containers
|
|
|
|
### Requirement: Service configuration
|
|
Each service SHALL be configured via environment variables defined in Docker Compose, with security best practices including non-root execution and security headers.
|
|
|
|
#### Scenario: Journal configuration
|
|
- **WHEN** the Journal container starts
|
|
- **THEN** it reads DOMAIN, DATABASE_URL, PLANNER_URL, JWT_SECRET, SESSION_SECRET, INTEGRATION_SECRET, WAHOO_* credentials, and SENTRY_DSN from environment variables
|
|
|
|
#### Scenario: Planner configuration
|
|
- **WHEN** the Planner container starts
|
|
- **THEN** it reads BROUTER_URL, DATABASE_URL, and INTEGRATION_SECRET from environment variables
|
|
|
|
#### Scenario: Caddy security headers
|
|
- **WHEN** Caddy proxies a request
|
|
- **THEN** it adds HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, and Permissions-Policy headers
|
|
|
|
#### Scenario: Caddy scanner blocking
|
|
- **WHEN** a request matches known scanner paths (.env, .git, wp-config, etc.)
|
|
- **THEN** Caddy returns 403 without forwarding to the application
|
|
|
|
### Requirement: PostgreSQL with PostGIS
|
|
The database SHALL be PostgreSQL with the PostGIS extension for spatial queries.
|
|
|
|
#### Scenario: PostGIS available
|
|
- **WHEN** the PostgreSQL container starts
|
|
- **THEN** the PostGIS extension is available and can be enabled with `CREATE EXTENSION postgis`
|
|
|
|
### Requirement: BRouter segment management
|
|
The infrastructure SHALL support downloading and updating planet-wide RD5 segments from brouter.de to the dedicated BRouter host. Segment files SHALL live under `~trails/brouter/segments/` on the dedicated host and SHALL be owned by the `trails` user.
|
|
|
|
#### Scenario: Download segments
|
|
- **WHEN** the segment download script runs on the dedicated host as the `trails` user
|
|
- **THEN** all planet-wide RD5 files referenced by the tile list are downloaded to `~trails/brouter/segments/`, skipping files that already exist
|
|
|
|
#### Scenario: Segment update
|
|
- **WHEN** an operator re-runs the segment download script
|
|
- **THEN** outdated or missing RD5 files are re-fetched from brouter.de and the BRouter container is restarted
|
|
|
|
### Requirement: CI/CD pipeline
|
|
GitHub Actions SHALL use separate workflows for app deployment, infrastructure deployment, and BRouter deployment, with secrets decrypted from a SOPS-encrypted file.
|
|
|
|
#### Scenario: App deployment
|
|
- **WHEN** code changes are pushed to main in apps/ or packages/
|
|
- **THEN** the cd-apps workflow builds Docker images, pushes to ghcr.io, and deploys app containers to the flagship host
|
|
|
|
#### Scenario: Infrastructure deployment
|
|
- **WHEN** changes are pushed to main in infrastructure/
|
|
- **THEN** the cd-infra workflow copies configs and restarts infrastructure services on the flagship host without rebuilding app images and without touching the BRouter host
|
|
|
|
#### Scenario: BRouter deployment
|
|
- **WHEN** changes are pushed to main in docker/brouter/ or the BRouter host compose config
|
|
- **THEN** the cd-brouter workflow SSHes as the `trails` user into the dedicated BRouter host using `BROUTER_DEPLOY_HOST` / `BROUTER_DEPLOY_SSH_KEY` and runs `docker compose up -d` in `~trails/brouter/`
|
|
|
|
#### Scenario: Secret decryption at deploy time
|
|
- **WHEN** `cd-apps.yml` runs
|
|
- **THEN** `secrets.app.env` is decrypted and injected into the Journal and Planner containers
|
|
- **WHEN** `cd-infra.yml` runs
|
|
- **THEN** both `secrets.app.env` and `secrets.infra.env` are decrypted and merged for infrastructure services
|
|
|
|
#### Scenario: Gitleaks scan
|
|
- **WHEN** a PR is opened
|
|
- **THEN** gitleaks scans for committed secrets
|
|
|
|
#### Scenario: Dependency audit
|
|
- **WHEN** CI runs
|
|
- **THEN** pnpm audit checks for high/critical vulnerabilities
|
|
|
|
### Requirement: Backup strategy
|
|
The infrastructure SHALL include daily backups of the PostgreSQL database.
|
|
|
|
#### Scenario: Daily backup
|
|
- **WHEN** the daily backup cron runs
|
|
- **THEN** a PostgreSQL dump is uploaded to the Hetzner Storage Box
|
|
|
|
### Requirement: Domain and TLS
|
|
The infrastructure SHALL configure DNS and TLS for trails.cool and planner.trails.cool.
|
|
|
|
#### Scenario: HTTPS access
|
|
- **WHEN** a user navigates to https://trails.cool
|
|
- **THEN** the connection is secured with a valid TLS certificate
|
|
|
|
### Requirement: Sentry error tracking
|
|
The system SHALL enrich Sentry events with user and session context, use route-aware tracing, and prevent source maps from being served to clients.
|
|
|
|
#### Scenario: Journal error includes user context
|
|
- **WHEN** an authenticated Journal user triggers an error
|
|
- **THEN** the Sentry event SHALL include the user's ID and username
|
|
|
|
#### Scenario: Journal error without user context
|
|
- **WHEN** an unauthenticated visitor triggers an error
|
|
- **THEN** the Sentry event SHALL have no user context (Sentry.setUser(null))
|
|
|
|
#### Scenario: Planner error includes session ID
|
|
- **WHEN** an error occurs during a Planner session
|
|
- **THEN** the Sentry event SHALL include a `session_id` tag with the active session ID
|
|
|
|
#### Scenario: Route-level performance traces
|
|
- **WHEN** a user navigates between routes in either app
|
|
- **THEN** Sentry SHALL create a transaction span named after the route pattern (e.g., `/routes/:id`)
|
|
|
|
#### Scenario: Source maps not served to clients
|
|
- **WHEN** a client requests a `.map` file from the production server
|
|
- **THEN** the server SHALL return 404 (source maps are uploaded to Sentry during build, not shipped in the bundle)
|
|
|
|
### Requirement: Grafana authentication
|
|
Grafana SHALL authenticate users via GitHub OAuth, restricted to the trails-cool GitHub organization.
|
|
|
|
#### Scenario: GitHub OAuth login
|
|
- **WHEN** a user navigates to grafana.internal.trails.cool
|
|
- **THEN** they are redirected to GitHub for authentication and granted access if they are a member of the trails-cool organization
|
|
|
|
#### Scenario: No password-based login
|
|
- **WHEN** Grafana is deployed
|
|
- **THEN** the login form is disabled and only GitHub OAuth is available
|
|
|
|
### Requirement: Grafana database access
|
|
The `grafana_reader` PostgreSQL role SHALL have SELECT access to the `pgboss` schema for job queue observability.
|
|
|
|
#### Scenario: Grant access on deploy
|
|
- **WHEN** the infrastructure deploy runs
|
|
- **THEN** `grafana_reader` is granted `USAGE` on the `pgboss` schema and `SELECT` on all tables in it
|
|
|
|
### Requirement: Monitoring stack
|
|
The Grafana Service Health dashboard SHALL include a job queue health panel.
|
|
|
|
#### Scenario: Job queue panel displays metrics
|
|
- **WHEN** a user views the Service Health dashboard
|
|
- **THEN** they see a panel showing job queue depth, completed jobs per hour, and failed jobs
|
|
- **AND** failed jobs are highlighted for investigation
|
|
|
|
### Requirement: Metrics collection
|
|
Prometheus SHALL scrape metrics from all application and infrastructure services.
|
|
|
|
#### Scenario: Exporter targets
|
|
- **WHEN** Prometheus is running
|
|
- **THEN** it scrapes metrics from journal (/api/metrics), planner (/metrics), postgres-exporter, node-exporter, cAdvisor, and Caddy (:2019)
|
|
|
|
#### Scenario: pg_stat_statements
|
|
- **WHEN** postgres-exporter scrapes PostgreSQL
|
|
- **THEN** slow query metrics from pg_stat_statements are exposed with query text via a custom queries config
|
|
|
|
### Requirement: Container log shipping
|
|
Promtail SHALL scrape all Docker container logs and push them to Loki for querying in Grafana.
|
|
|
|
#### Scenario: Logs visible in Grafana
|
|
- **WHEN** a container writes to stdout or stderr
|
|
- **THEN** the log line is available in Grafana Explore via Loki with container name labels
|
|
|
|
### Requirement: Caddy access logging
|
|
Caddy SHALL emit structured JSON access logs for all requests.
|
|
|
|
#### Scenario: Access log emitted
|
|
- **WHEN** any HTTP request passes through Caddy
|
|
- **THEN** a JSON log line with remote IP, method, path, status, and duration is written to stdout
|
|
|
|
### Requirement: Private network between flagship and BRouter hosts
|
|
The flagship host and the dedicated BRouter host SHALL be joined on a Hetzner vSwitch in the same datacenter. All traffic between Planner and BRouter SHALL traverse this private network.
|
|
|
|
#### Scenario: vSwitch reachability
|
|
- **WHEN** the flagship host issues a request to the BRouter host's vSwitch IP on the BRouter service port with a valid `X-BRouter-Auth` header
|
|
- **THEN** the request succeeds over the private network without traversing the public internet
|
|
|
|
#### Scenario: No public BRouter exposure
|
|
- **WHEN** Hetzner Cloud firewall rules or equivalent host firewall rules are inspected
|
|
- **THEN** no rule allows inbound traffic to the BRouter service port from any public IP
|
|
|
|
### Requirement: Non-root deploy user on the BRouter host
|
|
The BRouter host SHALL be administered by the trails.cool project through a non-root `trails` user that is a member of the `docker` group. The CD workflow SHALL NOT require sudo or root SSH access on this host.
|
|
|
|
#### Scenario: Deploy with trails user
|
|
- **WHEN** the cd-brouter workflow connects to the BRouter host
|
|
- **THEN** it authenticates as `trails` and successfully runs `docker compose` commands without invoking sudo
|
|
|
|
#### Scenario: Scoped ownership
|
|
- **WHEN** files are created by the deploy or segment-download scripts
|
|
- **THEN** they live under `~trails/brouter/` and are owned by `trails:trails`
|
|
|