.env.example

# Iter Maps server — configuration.
# Copy to `.env` and adjust. Every value here has a sensible default; the file
# documents the full stack's knobs. The backend takes NO host-side setup —
# `cp .env.example .env && podman compose -f docker/compose.yaml up` is the whole install.

# ─── Service bind / ports ────────────────────────────────────────────────────
GATEWAY_HOST=0.0.0.0
GATEWAY_PORT=8090
# Internal engine ports (container network only; no host ports in production).
OTP_PORT=8080
PHOTON_PORT=2322
STATIC_PORT=80

# Dev-only host ports (published only with `-f docker/compose.dev.yaml`, for LAN).
DEV_GATEWAY_PORT=8090
DEV_OTP_PORT=8080
DEV_PHOTON_PORT=2322
DEV_STATIC_PORT=8081

# Override files the refresh always re-applies (must persist exposure; P9).
# Empty = vanilla base (external-proxy model); `docker/compose.dev.yaml` for dev ports.
COMPOSE_FILES=

# ─── Upstream engines (as seen by the gateway) ───────────────────────────────
OTP_URL=http://otp:8080
PHOTON_URL=http://photon:2322

# Live-trains upstream (RFI ViaggiaTreno, unofficial public API).
VIAGGIATRENO_URL=http://www.viaggiatreno.it/infomobilita/resteasy/viaggiatreno
TRENITALIA_REGION=5

# Weather rerank factor (ADR 0033): keyless Open-Meteo forecast base URL for the
# opt-in `?rerank=<profile>` weather factor. Unset/empty disables it entirely
# (default-off): no outbound call, factor stays neutral. Coarse (~1 km) journey
# coordinates only, short timeout, TTL-cached, fail-soft.
WEATHER_API_URL=https://api.open-meteo.com/v1/forecast

# Place enrichment (ADR 0011): where Wikimedia data is *fetched* from. Unset uses
# the canonical per-service hosts (Wikipedia/Wikidata/Commons). Set it to a
# self-hosted mirror (or a test stub) that serves the three services under
# /wikipedia, /wikidata, /commons. Fetch URLs only — the public "view on Commons"
# provenance link and the /places/image proxy target stay canonical regardless.
# WIKIMEDIA_BASE_URL=

# GTFS-RT ingestion (worker reliability job): ATAC trip-updates feed + poll cadence.
# RT_TRIP_UPDATES_URL=https://romamobilita.it/wp-content/uploads/shared/rome_rtgtfs_trip_updates_feed.pb
RT_POLL_SECS=30

# Reliability rollup tier (ADR 0022): persistent Tier-0/1/2 aggregates derived
# from the GTFS-RT poll. Root dir defaults to a sibling of the graph under
# DATA_DIR; the rollup fold runs hourly. The worker writes it; the gateway reads
# the cold Tier-2 tier from the same dir to serve GET /reliability/* (ADR 0024),
# so point both tiers at one path.
# RELIABILITY_DIR=/data/reliability
RELIABILITY_ROLLUP_SECS=3600

# Crowd telemetry wave 1 (ADR 0046): opt-in POST /telemetry ingest and the
# k-anonymous rollup job. Enabled in this reference deployment; PUBLIC
# exposure additionally requires the rate-limiting proxy (docs/OPERATIONS.md,
# `--profile edge`) — the endpoint is auth-less by design. Set the flag on
# BOTH the gateway and the worker; set 0 to disable (404, GC still drains). Spool/aggregates live under DATA_DIR/telemetry unless
# TELEMETRY_DIR overrides (the compose stack mounts a dedicated writable
# volume at /telemetry — the gateway's artifact tree stays read-only); the
# fold runs hourly.
TELEMETRY_INGEST_ENABLED=1
# TELEMETRY_DIR=/data/telemetry
# TELEMETRY_ROLLUP_SECS=3600

# E2EE cross-device sync (ADR 0049): opt-in opaque blob store on /sync/{keyId}.
# The server holds ciphertext it can never read; the client-derived key id is
# the only credential. Enabled in this reference deployment; PUBLIC exposure
# additionally requires the rate-limiting proxy (docs/OPERATIONS.md). Set 0
# to disable — the routes 404 and no new state is created.
# The flag gates the gateway; the worker's sync-gc job always runs and unlinks
# blobs not written for SYNC_RETAIN_DAYS. Blobs live under DATA_DIR/sync
# unless SYNC_DIR overrides (the compose stack mounts a dedicated writable
# volume at /sync — the gateway's artifact tree stays read-only).
# SYNC_MAX_TOTAL_BYTES is the global disk-fill bound (default 1 GiB).
SYNC_ENABLED=1
# SYNC_DIR=/data/sync
# SYNC_MAX_TOTAL_BYTES=1073741824
# SYNC_RETAIN_DAYS=365
# SYNC_GC_SECS=86400

# Traffic rerank factor (ADR 0043): a DATEX II situation-publication URL (e.g.
# the CCISS NAP feed once provisioned). Default OFF — unset means no outbound
# call and a neutral factor.
# TRAFFIC_DATEX_URL=

# Wikivoyage collections fetch seam (ADR 0042): reroute the /places/collections
# guide fetch to a mirror or test stub. Unset uses the canonical
# https://<lang>.wikivoyage.org; the attribution URL stays canonical regardless.
# WIKIVOYAGE_BASE_URL=

# Scheduled refresh preset (ADR 0040): set by the cron/CronJob entry that
# re-runs the pipeline. daily = fresh feeds + graph; monthly = superset adding
# the OSM side (source, clip, overlays, tiles, pathways). Unset for normal
# bootstrap runs; any other value aborts loudly.
# PIPELINE_REFRESH=daily

# Station pathways (ADR 0039/0053): derive GTFS Pathways from OSM indoor
# structures and patch them into the metro feed for in-station routing.
# Default ON since ADR 0053 (verified end-to-end); set 0 to opt out — the
# next pipeline run un-patches the feed.
# PATHWAYS_ENABLED=1

# FL NeTEx→GTFS (worker): auto-downloads the Lazio NeTEx from the Italian NAP
# (CCISS public endpoint, no auth) by default — RAP Lazio L2. Set NETEX_URL=
# (empty) to disable the fetch and use a file placed at GATEWAY_NETEX_PATH, or
# point it at another NAP asset.
# NETEX_URL=https://www.cciss.it/nap/mmtis/public/api/v1/download/blob/Asset/663391/checkedResource
# GATEWAY_NETEX_PATH=/data/netex/trenitalia-fl.netex.xml.gz

# ─── Observability (operator-local; never phones home) ───────────────────────
ITER_LOG=info
# ITER_LOG_FORMAT=json
# ITER_VERSION=
# Internal Prometheus /metrics (ADR 0037) — proxy-gated, never public. Set 0 to
# turn it off (404).
# METRICS_ENABLED=1
# Curated GET /stats JSON summary (ADR 0038) — safe aggregates only; public
# exposure is the proxy's routing decision. Set 0 to turn it off (404).
# STATS_ENABLED=1

# ─── Artifacts ───────────────────────────────────────────────────────────────
# Root of the regenerable artifact tree (graph, index, tiles, overlays). Never
# committed to git; rebuilt from public sources on first boot (P7).
DATA_DIR=/data

# ─── Region ──────────────────────────────────────────────────────────────────
# Deployment target in the region tree (regions/<path>/region.toml). Its
# resolved profile supplies the extents, feeds, geocoding, and overlays — so the
# extents below are overrides, not the source of truth. Required: there is no
# in-code default; the pipeline, gateway, and worker all abort at startup
# without it.
ITER_REGION=italy/lazio/rome
REGIONS_DIR=regions

# ─── Geographic extents (overrides for the resolved region) ──────────────────
# The region profile is the source of truth; set a var here only to override on
# a specific host. minLon,minLat,maxLon,maxLat.
# Transit/walk routing clip — region default = Lazio. Shrink for a small host:
# ROUTING_BOUNDS=12.40,41.78,12.62,41.99   # central Rome
# Basemap tile extent — region default = all-Italy. Shrink to fit a small host
# (lower PLANETILER_HEAP to match):
# PMTILES_BOUNDS=6.6,35.3,18.6,47.1
# House-number (civici) extraction extent. Default ≈ Rome + belt.
CIVICI_BBOX=12.10,41.60,12.95,42.20

# ─── Engine memory (JVM heaps; size container limits ~1.25–1.5x these) ────────
OTP_HEAP=4g
OTP_BUILD_HEAP=8g
PHOTON_HEAP=1g
PHOTON_IMPORT_HEAP=2g
PLANETILER_HEAP=12g

# ─── Geocoding ───────────────────────────────────────────────────────────────
# The region profile supplies the Photon dump URL + country/languages; these
# override per host. Country/languages are applied at import (rebuild to change).
# PHOTON_DUMP_URL=         # default = region geocoding.photon_dump
PHOTON_COUNTRY_CODES=it
PHOTON_LANGUAGES=it,en
# Civici (Italian house numbers) from Overture addresses, by CIVICI_BBOX above.
CIVICI_ENABLE=true
# Overture release to read; files are retained ~60 days, so bump as releases roll.
CIVICI_OVERTURE_RELEASE=2026-06-17.0

# ─── Offline pre-download caps (only abuse protection on this public surface) ──
OFFLINE_MAX_AREA_DEG2=6
OFFLINE_MAX_ZOOM=14
OFFLINE_MAX_CONCURRENT=3

# ─── Data sources ────────────────────────────────────────────────────────────
# Dev = central Italy; production all-Italy basemap = europe/italy-latest.osm.pbf
# OSM source extract. Default comes from the region tree ([osm] url — the
# regione's Geofabrik cut); set this only to override it for a deploy.
# GEOFABRIK_OSM_URL=

# ─── Pipeline step controls (idempotent; skip-if-present by default) ──────────
# FORCE_<step> re-runs one step; SKIP_<step> opts out. Steps: OSM CLIP GTFS
# BUILD_CONFIG GRAPH OVERLAY CIVICI PHOTON PLACES TILES HEALTH (and, as they
# land, STYLES GLYPHS). Note: FORCE_CIVICI alone re-extracts the house docs but
# only reaches the served index on a reimport — pair with FORCE_PHOTON.
FORCE_ALL=false
# Addressed-POI (place-correlation) extract extent; defaults to CIVICI_BBOX.
# PLACES_BBOX=12.10,41.60,12.95,42.20
# Narrow the GTFS fetch to a comma-separated feedId allow-list (empty = all
# enabled feeds), e.g. to refresh just one operator: GTFS_FEEDS=ATAC
# GTFS_FEEDS=
FORCE_GRAPH_REBUILD=false
# Daily graph swap: false = zero-downtime (old graph serves while new builds);
# true = stop services during build (low-RAM hosts).
GRAPH_REBUILD_STOP_SERVICES=false
# SKIP_HEALTH=false

# ─── Declarative proxy discovery (the NAME is the signal; keep values EMPTY) ──
SERVICE_URL_GATEWAY_8090=
SERVICE_URL_OTP_8080=
SERVICE_URL_PHOTON_2322=
SERVICE_URL_STATIC_80=