docs: REDIS_ADDR in env template, channel/trace IATA tables

The example .env never set REDIS_ADDR, so stacks built from it ran
with caching silently off. Also document the channels list IATA
filter and the new channel_iatas/trace_iatas tables.

README.md

@@ -58,6 +58,7 @@ Set every `CHANGE_*` value. The variables you must fill in:
 | Variable | Service | What to set |
 |---|---|---|
 | `POSTGRES_DSN` | `app` | Database connection string. Change the password (`CHANGE_DB_PASS`) to a strong one. |
+| `REDIS_ADDR` | `app` | `redis:6379` — points the API at the compose Redis service. Leave it out and the server runs uncached, so every read hits Postgres. |
 | `MQTT_BROKER_1_*` / `MQTT_BROKER_2_*` | `app` | URL, username, and password for your live MeshCore MQTT packet sources. |
 | `DOMAIN` | `caddy` | Your public domain (e.g. `beacon.example.com`). Caddy auto-provisions a Let's Encrypt cert for it. |
 | `VITE_API_BASE` | `web` | `https://<your-domain>/api/v1` — must be the **public** domain, never localhost. |

app_config/.env.example

@@ -14,6 +14,10 @@ LISTEN_ADDR=:8080
 # must match POSTGRES_PASSWORD in docker-compose.yml.
 POSTGRES_DSN=postgres://tower:CHANGE_DB_PASS@db:5432/tower?sslmode=disable
 
+# Redis cache. Host "redis" is the compose service name. If unset, the
+# server runs with caching disabled and every read hits Postgres.
+REDIS_ADDR=redis:6379
+
 # ---- MQTT ingest brokers (service: app) ---------------------
 # Live packet sources. Put your real passwords back here.
 MQTT_BROKER_1_URL=wss://mqtt1.meshcore.ca:443

app_documentation/api_contract.md

@@ -742,11 +742,14 @@ Telemetry response is a time-bucketed array suitable for direct chart consumptio
 ### Channels
 
 ```
-GET    /api/v1/channels?limit=50
+GET    /api/v1/channels?iata=YOW&limit=50
 GET    /api/v1/channels/{channelHash}
 GET    /api/v1/channels/{channelHash}/messages?since=<ts>&limit=50&cursor=<opaque>
 ```
 
+The list accepts a single `iata=` or comma-separated `iatas=YOW,YYZ` (case-insensitive)
+and returns channels heard in those IATAs within the packet retention window.
+
 Channel keys are configured via the server config file.
 
 ### IATAs and regions

app_documentation/high_level_design.md

@@ -592,6 +592,28 @@ CREATE TABLE channels (
 
 CREATE INDEX idx_channels_last_seen ON channels(last_seen DESC);
 
+-- Which IATAs each channel has been heard in, maintained at ingest and
+-- pruned on the packet retention cutoff. Backs the channel list IATA
+-- filter without touching packet_observations. trace_iatas does the
+-- same for trace tags.
+CREATE TABLE channel_iatas (
+  channel_hash BYTEA NOT NULL,
+  iata         CHAR(3) NOT NULL REFERENCES iata_codes(iata) ON DELETE CASCADE,
+  last_heard   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (channel_hash, iata)
+);
+
+CREATE INDEX idx_channel_iatas_iata ON channel_iatas(iata, last_heard DESC);
+
+CREATE TABLE trace_iatas (
+  trace_tag  BYTEA NOT NULL,
+  iata       CHAR(3) NOT NULL REFERENCES iata_codes(iata) ON DELETE CASCADE,
+  last_heard TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (trace_tag, iata)
+);
+
+CREATE INDEX idx_trace_iatas_iata ON trace_iatas(iata, last_heard DESC);
+
 -- Channel decryption keys, loaded from the server config file on startup.
 -- Adding or rotating a key requires updating the config and restarting (or SIGHUP).
 CREATE TABLE channel_keys (