trails/openspec/specs/infrastructure/spec.md

ADDED 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 CX21 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 on the Hetzner server.

Scenario: Start all services

• WHEN docker compose up -d is run on the server
• THEN the Journal, Planner, BRouter, PostgreSQL, and Garage containers start and are reachable

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, S3_ENDPOINT, and S3_BUCKET from environment variables

Scenario: Planner configuration

• WHEN the Planner container starts
• THEN it reads BROUTER_URL and DATABASE_URL 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 Germany RD5 segments from brouter.de.

Scenario: Download segments

• WHEN the segment download script is run
• THEN Germany RD5 files (E5_N45, E5_N50, E10_N45, E10_N50) are downloaded to the segments volume

Scenario: Weekly segment update

• WHEN the weekly cron job runs
• THEN RD5 segments are updated from brouter.de and the BRouter container is restarted

Requirement: CI/CD pipeline

GitHub Actions SHALL build, deploy, and security-scan both apps on push to main.

Scenario: Push triggers deployment

• WHEN code is pushed to the main branch
• THEN GitHub Actions builds Docker images, pushes to ghcr.io/trails-cool/, and deploys to the Hetzner server

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)