Redis cache
Switch CACHE_PROVIDER to Redis and configure REDIS_* variables for OpenQuok.
Connect your agent today
Draft from chat, review in your calendar, and publish only what you approve.
Overview
By default the backend uses Redis for cache (CACHE_PROVIDER=redis). For local development, run Redis via Docker (recommended); if you don’t want Redis locally, you can fall back to CACHE_PROVIDER=memory.
The same REDIS_HOST / REDIS_PORT / REDIS_PASSWORD values are also used for BullMQ when integration refresh runs in distributed mode (transport: bullmq in backend/config/orchestratorFlows.ts). That path uses the Flowcraft distributed execution model with the BullMQ adapter and a dedicated BullMQ client (ioredis), not the redis package used by RedisCacheProvider. Optional REDIS_BULLMQ_DB selects the logical Redis database for queues (defaults to REDIS_DB).
Steps
Create a Redis database
If you don’t have Redis already, you can create one via Redis Cloud (or your preferred provider).
Once the database is ready, open your provider’s configuration/settings page and collect:
| Detail | Where to find it |
|---|---|
| Host | Public endpoint, the hostname portion (e.g. redis-*****18904.*.ap-southeast-1-1.ec2.cloud.redislabs.com) |
| Port | Public endpoint, the port number after : (e.g. 18903) |
| Password | Database Security section (often “Default user password”) |
Local development (Docker)
The repo includes a minimal local Redis in infra/docker-compose.yml. This is the recommended way to run Redis for local development so your API + workers never accidentally point at a shared production instance.
# From repo root
docker compose -f infra/docker-compose.yml up -d redisTo stop it:
docker compose -f infra/docker-compose.yml downThen configure backend/.env.development.local to point at Docker:
CACHE_PROVIDER=redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
REDIS_TLS=false
REDIS_TLS_REJECT_UNAUTHORIZED=true
REDIS_BULLMQ_DB=0Set the backend env variables
Edit backend/.env.development.local (or your production env). A typical Redis-backed setup looks like this (use your provider’s host, port, and password — do not commit real secrets):
# -----------------------------------------------------------------------------
# Cache (memory or redis; used for module_configs etc.)
# -----------------------------------------------------------------------------
CACHE_PROVIDER=redis
CACHE_DEFAULT_TTL=900
CACHE_LOG_HITS=true
CACHE_LOG_MISSES=true
CACHE_CHECK_PERIOD=60
CACHE_USE_CLONES=false
CACHE_ENABLED=true
CACHE_ENABLE_PATTERNS=true
# Redis (when CACHE_PROVIDER=redis). Point at your local or managed Redis host.
# These placeholder lines target localhost:6379 with no password — they will FAIL integration checks
# (e.g. pnpm test:integration:bullmq-redis) unless you run Redis locally (e.g. Docker). Copy real host/port/password
# from your provider into .env.development.local; managed Redis often needs REDIS_TLS=true as well.
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
REDIS_TLS=false
REDIS_TLS_REJECT_UNAUTHORIZED=true
REDIS_PREFIX=app:cache:
REDIS_MAX_RECONNECT_ATTEMPTS=10
REDIS_ENABLE_OFFLINE_QUEUE=true
REDIS_USE_SCAN=true
# Optional: logical Redis DB for BullMQ / Flowcraft queues (defaults to REDIS_DB).
REDIS_BULLMQ_DB=0For Redis-backed cache, set CACHE_PROVIDER=redis and replace the placeholder REDIS_HOST / REDIS_PORT / REDIS_PASSWORD with your provider values. Managed hosts often need REDIS_TLS=true (and only in local dev, if required, REDIS_TLS_REJECT_UNAUTHORIZED=false).
Integration token refresh in BullMQ mode uses the same REDIS_* connection. Set orchestratorFlows.integrationRefresh.transport to bullmq in backend/config/orchestratorFlows.ts (enabled, queue name, and transport are documented there). See Backend orchestrator workflows.
Verify the connection
Start the backend and look for a Redis “connected” log line. If you see connection failures, re-check host/port/password.
You can also run these opt-in smoke tests:
# Local dev / Docker Redis (uses backend/.env.development.local)
cd backend
pnpm test:integration:bullmq-redis
pnpm test:integration:third-parties:redis
# Production-connection smoke test (uses backend/.env.production.local)
pnpm test:integration:third-parties:prod:redisOptional: BullMQ connectivity (distributed refresh worker)
With Redis running, you can confirm the queue client from the backend package:
cd backend
pnpm test:integration:bullmq-redisThen run the worker (after setting transport: bullmq for integration refresh in backend/config/orchestratorFlows.ts and redeploying the API):
# From repository root (recommended)
pnpm orchestrator:dev:worker:integration-refresh-bullmqFor production worker hosts (always-on), use pnpm railway:orchestrator:build and pnpm railway:orchestrator:start:integration-refresh as documented in Configuration - Worker and Railway (orchestrator workers).