trails/docs/ideas/self-host-overpass/specs/infrastructure/spec.md at c4874dc04c0a62796cf628c7c7a133cb0783e42b

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

2.1 KiB

Raw Blame History

ADDED Requirements

Requirement: Separate Overpass host

The trails.cool infrastructure SHALL include a second Hetzner host, distinct from the existing compose host, dedicated to running the Overpass service and its OSM data volume.

Scenario: Host isolation

WHEN the operator provisions the Overpass host
THEN it runs only the Overpass stack (plus its firewall/tooling) and shares no filesystem, database, or container with the existing trails.cool compose host

Scenario: Host-specific configuration lives in its own directory

WHEN a change is made to the Overpass host configuration
THEN the change is contained to a dedicated infrastructure/overpass-host/ directory (compose file, Dockerfile wrapper, firewall rule template, load scripts) and does not touch the existing compose stack

Requirement: Planner-side configuration for the Overpass proxy

The Planner container SHALL read the Overpass endpoint from an environment variable so the target host can be swapped without code changes.

Scenario: Endpoint configurable

WHEN the operator sets OVERPASS_URL on the Planner container to any reachable Overpass endpoint
THEN the Planner proxy route forwards queries to that endpoint without a rebuild or code change

Scenario: Missing configuration handled gracefully

WHEN OVERPASS_URL is unset or empty
THEN the Planner proxy responds with a service-unavailable status and a log message, rather than contacting an unintended default

Requirement: Overpass observability

The infrastructure SHALL surface basic Overpass health signals via the existing Prometheus / Grafana stack.

Scenario: Service up metric

WHEN Prometheus scrapes the overpass service (directly or via a sidecar exporter / blackbox probe)
THEN an overpass_up gauge reflects whether the service is responding to health checks

Scenario: Replication lag metric

WHEN Prometheus scrapes the overpass replication state
THEN a metric reports the age of the most recently applied OSM diff, so alerts can fire when lag exceeds 48 hours

2.1 KiB Raw Blame History