From 30c101d190aef5a438fe7fb688dacd99cf94b950 Mon Sep 17 00:00:00 2001 From: MrAlders0n Date: Thu, 23 Jul 2026 12:21:21 -0400 Subject: [PATCH] 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 | 1 + app_config/.env.example | 4 ++++ app_documentation/api_contract.md | 5 ++++- app_documentation/high_level_design.md | 22 ++++++++++++++++++++++ 4 files changed, 31 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7e78bad..1c12f3a 100644 --- a/README.md +++ b/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:///api/v1` — must be the **public** domain, never localhost. | diff --git a/app_config/.env.example b/app_config/.env.example index 7bf25c0..54c0004 100644 --- a/app_config/.env.example +++ b/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 diff --git a/app_documentation/api_contract.md b/app_documentation/api_contract.md index 1453907..57271a7 100644 --- a/app_documentation/api_contract.md +++ b/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=&limit=50&cursor= ``` +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 diff --git a/app_documentation/high_level_design.md b/app_documentation/high_level_design.md index 148dda6..02af2db 100644 --- a/app_documentation/high_level_design.md +++ b/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 (