homepage/tile-proxy/README.md

tile-proxy

A tiny region-switching map-tile service for the hikes maps. It exposes one canonical XYZ scheme and, per tile, serves swisstopo inside Switzerland & Liechtenstein and a global provider elsewhere — so a hike anywhere in the world gets a good schematic + satellite basemap, while CH/LI hikes keep swisstopo quality.

browser / build script
        │   https://maps.bocken.org/{layer}/{z}/{x}/{y}
        ▼
   nginx   ── TLS termination + on-disk tile cache (proxy_cache)
        ▼   http://$TILE_PROXY_ADDR   (default 127.0.0.1:8765)
  tile-proxy (this crate)  ── z/x/y → point-in-polygon → pick + fetch upstream
        ▼
  swisstopo  │  OpenTopoMap  │  Esri World Imagery

The listen address is set entirely by the TILE_PROXY_ADDR env var (host:port); pick whatever port you like. nginx, the systemd unit and this binary all reference that one value.

Caching/TLS/rate-limiting live in nginx (Arch's stock nginx has no njs, and we want a real geometry test anyway). This binary only does routing + fetch and is stateless.

Layers & providers

{layer}	swisstopo region (CH + LI)	elsewhere
karte	ch.swisstopo.pixelkarte-farbe	Thunderforest Outdoors (or OpenTopoMap)
luftbild	ch.swisstopo.swissimage	Esri World Imagery
dufour	ch.swisstopo.hiks-dufour	— (CH/LI-only)

The karte upstream abroad is Thunderforest Outdoors when a THUNDERFOREST_API_KEY is available at build time — it's baked into the binary via option_env!. The key is read from tile-proxy/.env (gitignored) by build.rs, or from a shell env var of the same name; both are watched so the binary recompiles whenever the value changes. Without a key, the build falls back to OpenTopoMap (no key needed, but its hypsometric tint reads as "red mountains / green flats", which is why Thunderforest is preferred when available).

# tile-proxy/.env  (gitignored)
THUNDERFOREST_API_KEY=your-key-here

The swisstopo region is Switzerland + Liechtenstein (swisstopo has high-quality data for both). A tile is served by swisstopo when it overlaps that region at all — the tile's lat/lng rectangle is intersected against the polygons (src/regions.in, simplified + a 2 km outward buffer), so any tile touching CH/LI gets swisstopo, at every zoom. (A swisstopo tile partly outside its data just renders white at the edges, which beats a foreign provider drawing over covered ground.) For karte/luftbild, a swisstopo tile that 404s near the edge falls back to the global provider automatically.

Build & run

# Optional: drop a Thunderforest key in tile-proxy/.env for nicer abroad
# `karte` tiles; the build falls back to OpenTopoMap when the file is absent.
echo 'THUNDERFOREST_API_KEY=your-key-here' > .env
cargo build --release
TILE_PROXY_ADDR=127.0.0.1:8765 ./target/release/tile-proxy
# smoke test
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' \
  http://127.0.0.1:8765/karte/9/266/180        # Bern  → swisstopo (jpeg)
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' \
  http://127.0.0.1:8765/karte/9/255/171        # London → Thunderforest / OpenTopoMap (png)

TILE_PROXY_ADDR defaults to 127.0.0.1:8765 but should be set explicitly. GET /healthz returns ok.

Run it as a service with deploy/tile-proxy.service and put nginx in front with deploy/nginx.conf.example.

Regenerating the region polygons

src/regions.in is generated — don't hand-edit it. To refresh (or change the buffer / simplification, or add a region):

make regions                                    # CH + LI, default 2 km buffer
BUFFER_KM=2 SIMPLIFY_DEG=0.004 node scripts/gen-regions.mjs
node scripts/gen-regions.mjs ./ch.geojson ./li.geojson   # local files

It takes each source's largest exterior ring, Douglas–Peucker–simplifies it, then pushes every vertex outward by BUFFER_KM. Rebuild the binary afterwards (the ring is baked in via include!). If you move the boundary, purge the nginx cache so old tiles aren't served by the previous provider.

Attribution (required)

All providers require credit — keep these on the page (the hikes pages show them in the footer):

• © swisstopo — Swiss tiles.
• Maps © Thunderforest, Data © OpenStreetMap contributors — world schematic (when the key is baked in).
• © OpenStreetMap contributors, SRTM | © OpenTopoMap (CC-BY-SA) — world schematic (fallback build).
• © Esri, Maxar, Earthstar Geographics — world satellite.

Notes

• Max zoom differs by provider — clamp the client: OpenTopoMap 17, Esri imagery ~19, swisstopo 19/20.
• OpenTopoMap fair-use: it's a small volunteer project; the long nginx cache + a descriptive User-Agent is the mitigation. If traffic grows, self-host a renderer.
• Dufour has no world equivalent — the client hides that layer when the view leaves Switzerland.