trails-cool/trails
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
trails/docs/ideas/self-host-overpass/specs/overpass-hosting/spec.md
Ullrich Schäfer c4874dc04c
Park self-host-overpass spec under docs/ideas 
The interim proxy (#239/#240/#242/#243) covers the day-one needs for
Overpass — User-Agent compliance via server-side proxy, same-origin +
rate limit + cache with coalescing, bbox quantization, observability.
Further work on self-hosting the upstream is no longer urgent.

Move the full OpenSpec artifact set out of openspec/changes/ so it
doesn't clutter the active change list, and park it under
docs/ideas/self-host-overpass/ as a reference for when we revive it.
Adds a short README at the new location capturing:
- current interim solution
- triggers that would justify reviving (rate limits, >1 req/s, etc.)
- key decisions already made (Hetzner-to-Hetzner firewall model,
  DOCKER-USER chain, capacity ceiling at DACH on current box)
- how to switch when the time comes (flip OVERPASS_URL, no client
  changes)

The files were never committed in the first place (WIP in the working
tree through the proposal session), so no git history to preserve.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-19 07:40:44 +02:00

4.8 KiB
Raw Blame History

ADDED Requirements

Requirement: Self-hosted Overpass service

The trails.cool infrastructure SHALL run an Overpass API instance as a Docker service on a dedicated host, populated from a configurable regional OpenStreetMap extract, and reachable only from the Planner host.

Scenario: Service reachable from the Planner host

  • WHEN the Planner server sends an Overpass query from its configured egress address to the Overpass host on the configured port
  • THEN the request is accepted and served

Scenario: Service not reachable from any other source

  • WHEN any other host on the public internet attempts to connect to the Overpass host's Overpass port
  • THEN the connection is dropped by the host firewall and the Overpass service never sees the packets

Scenario: Regional extract is configurable

  • WHEN the operator sets a different OVERPASS_PBF_URL and runs the initial-load procedure
  • THEN the service comes up populated from that extract without code changes

Requirement: Firewall compatible with Docker

The Overpass host firewall SHALL enforce the allowlist in a way that survives Docker daemon restarts, container restarts, and port-publication rule changes — i.e. user rules MUST be placed on the chain Docker reserves for user-managed filtering rather than relying on chains that Docker bypasses when publishing container ports.

Scenario: Rule survives container restart

  • WHEN the Overpass container is stopped and started
  • THEN the firewall allowlist is still in effect and unauthorised sources are still dropped without operator intervention

Scenario: Rule survives Docker daemon restart

  • WHEN the Docker daemon on the Overpass host is restarted
  • THEN the firewall allowlist is still in effect and unauthorised sources are still dropped without operator intervention

Scenario: Planner host address change

  • WHEN the Planner host's egress address changes and the operator updates the configured allowlist address
  • THEN applying the updated ruleset restores Planner connectivity without requiring Docker or Overpass to restart

Requirement: Overpass data refresh

The Overpass service SHALL keep its OSM database current by applying upstream diffs on a recurring schedule without manual intervention after the initial import.

Scenario: Daily replication

  • WHEN 24 hours have passed since the last diff application
  • THEN the container has fetched and applied the next diff from the upstream provider, and the replication timestamp advances

Scenario: Recoverable replication failure

  • WHEN diff replication fails once (network blip, upstream 5xx)
  • THEN the container retries on its next scheduled interval without requiring an operator to restart it

Scenario: Replication lag observable

  • WHEN replication has been failing for more than 48 hours
  • THEN a monitoring signal indicates the service is stale so the operator can investigate

Requirement: Planner Overpass proxy route

The Planner server SHALL expose an authenticated, rate-limited proxy route that forwards Overpass QL queries to the Overpass host. This SHALL be the only path through which Overpass is reachable from outside the Overpass host.

Scenario: Forward valid query

  • WHEN an authenticated Planner browser session POSTs a valid Overpass QL query to /api/overpass
  • THEN the proxy forwards the query to the Overpass service and returns the upstream response body and status

Scenario: Reject unauthenticated request

  • WHEN a request arrives at /api/overpass without a valid Planner session cookie
  • THEN the proxy responds with HTTP 401 and does not contact the Overpass service

Scenario: Reject cross-origin request

  • WHEN a request arrives at /api/overpass with an Origin header not matching the Planner's own origin
  • THEN the proxy responds with HTTP 403 and does not contact the Overpass service

Scenario: Rate limit exceeded

  • WHEN a session sends more Overpass queries than the configured per-session limit allows within the rate-limit window
  • THEN the proxy responds with HTTP 429 and does not contact the Overpass service

Requirement: Initial data load is out-of-band

The initial import of the regional OSM extract into the Overpass database SHALL NOT run as part of a normal deploy and SHALL NOT block routine container restarts once the data volume is populated.

Scenario: First-time setup

  • WHEN the operator provisions a new Overpass host with an empty data volume
  • THEN a documented one-shot procedure (e.g. a compose-run command) performs the initial PBF download and import, and exits cleanly

Scenario: Routine restart

  • WHEN the overpass service is restarted with an already-populated data volume
  • THEN the service comes up and is query-ready without re-importing data