Phase 35 of v1.5 MCP Public-Launch Hardening (DEPLOY-01..04): - DEPLOY-01: production and cloud compose now provision a co-located Redis (password-protected via REDIS_PASSWORD, internal-only) and wire REDIS_URL, so sessions, command queue, geocode cache, and rate limiters work in prod. - DEPLOY-02: set WWV_DATA_ENGINE_URL to the engine REST base (not the NEXT_PUBLIC_.../stream WS URL) so MCP data tools reach /manifest. - DEPLOY-03: a single global 1 req/s Nominatim throttle (peek/commit sliding window with a queued-waiter cap and an in-process fallback) protects the shared geocoder; the 24h cache is checked before the throttle. - DEPLOY-04: deploy/INFRA-CHECKLIST.md documents the operator actions (managed Redis rediss://, WWV_DATA_ENGINE_URL, distinct API_KEY_HMAC_SECRET, AUTH_SECRET, WWV_TRUSTED_IP_HEADER for multi-proxy, health semantics). Security hardening from review: require AUTH_SECRET (no weak committed fallback), password the co-located Redis, bind cloud Postgres to loopback, de-duplicate the geocode result normaliser. Patch.
4.6 KiB
Production Infrastructure Checklist
Actions an operator must apply in Coolify (or equivalent) before public launch. Complete every item and verify the /api/health response before opening traffic.
1. AUTH_SECRET
- Generate a high-entropy secret (minimum 32 bytes):
openssl rand -hex 32 - Set it as
AUTH_SECRETon thewwvservice. This value MUST be distinct fromAPI_KEY_HMAC_SECRET. The app fails closed (auth broken) if this is unset.
2. Redis
- Generate a Redis password:
openssl rand -hex 32 - Set
REDIS_PASSWORDon both thewwvandwwv-redisservices to this value. - For a co-located
wwv-redis: the compose default uses this password automatically viaREDIS_URL=redis://:<password>@wwv-redis:6379. No further URL override is needed. - For a managed Redis provider (e.g. Upstash, Redis Cloud): set
REDIS_URLto the provider's TLS endpoint instead:UseREDIS_URL=rediss://:<password>@<host>:<port>rediss://(double-s) for TLS. Remove the co-locatedwwv-redisservice when using a managed provider. - Verify Redis is reachable:
GET /api/healthshould return200with"redis": "ok"(not"degraded").
What breaks without Redis: MCP sessions, globe command queue, geocode cache, all per-user and global rate limiters, and API key session tracking silently no-op or degrade. The app stays up but MCP data tools report errors and OSM rate limits are unenforceable.
3. Data Engine REST URL
- Set
WWV_DATA_ENGINE_URLon thewwvservice to the engine's REST base URL. This is the HTTP base (scheme + host + port). Do NOT include the/streampath:The engine's published REST port is 5002 (maps to internal port 5000 in# Correct: REST base only WWV_DATA_ENGINE_URL=http://<engine-host-ip>:5002 # Wrong: do not include /stream # WWV_DATA_ENGINE_URL=http://<engine-host-ip>:5002/streamdeploy/production/docker-compose.engine.yml). Replace<engine-host-ip>with the actual engine host IP or hostname visible from thewwvcontainer. - If the app and engine containers share a Docker network, use the service name:
WWV_DATA_ENGINE_URL=http://wwv-data-engine:5000 - Verify reachability:
GET /api/healthshould return"engine": "ok". A value of"degraded"means the URL is wrong or the engine is not running.
What breaks without this: All MCP data query tools (e.g. query_plugin_data)
report "engine unreachable" and return no data.
4. API Key HMAC Secret
- Generate a high-entropy secret (minimum 32 bytes):
openssl rand -hex 32 - Set it as
API_KEY_HMAC_SECRETon thewwvservice. This value MUST be distinct fromAUTH_SECRET. They serve different cryptographic purposes. - cloud and demo editions fail closed without this value. The app will refuse to issue or validate API keys, blocking all MCP authentication.
5. Trusted IP Header (Cloudflare / CDN)
- If a CDN or second reverse proxy (e.g. Cloudflare) sits in front of your
Nginx/Traefik reverse proxy, set:
Without this, all clients share the proxy's IP address and collapse into a single rate-limit bucket. One user's burst exhausts the quota for all users.
WWV_TRUSTED_IP_HEADER=cf-connecting-ip - If you are NOT behind Cloudflare, leave
WWV_TRUSTED_IP_HEADERunset (the default reads fromx-forwarded-forviax-real-ip). - Verify the correct client IP is visible in request logs or the
X-Client-IPdebug header (if enabled) after applying the setting.
6. Health Check Semantics
Configure your uptime monitor or Coolify health check against GET /api/health.
| Response | Meaning | Action required |
|---|---|---|
503 |
Database or required config broken | Page on-call immediately |
200 with any "degraded" field |
Redis or engine unreachable | Investigate; MCP features are impaired but core app is up |
200 all "ok" |
Fully healthy | No action |
Recommended alert rule: alert on any 503 immediately; alert on 200 degraded
after 5 consecutive checks (transient restarts are normal).
Verification Sequence
Run these checks in order after applying all settings:
GET /api/healthreturns200with all fields"ok".- Sign in as an admin user, generate an MCP API key, and confirm the key is issued
(cloud/demo: requires
API_KEY_HMAC_SECRET). - Run
geocode_location({ query: "Paris" })via the MCP endpoint and confirm results are returned (requires Redis + Nominatim reachability). - Run
query_plugin_datafor a live plugin and confirm data is returned (requiresWWV_DATA_ENGINE_URL).