Configuration

The Realtime Platform uses a Zod-validated configuration system loaded from environment variables. All backend services share the same configuration schema defined in the @realtime/shared-config package.

Environment Variables

Backend Server

Variable	Required	Default	Description
`NODE_ENV`	No	`development`	`development` \| `staging` \| `production` \| `test`
`PORT`	No	`3000`	HTTP server listen port
`LOG_LEVEL`	No	`info`	`debug` \| `info` \| `warn` \| `error`

PostgreSQL (Platform Database)

The platform's own metadata database for topics, schemas, mappings, keys, migrations, users, etc.

Variable	Required	Default	Description
`DATABASE_URL`	No	—	Full connection string (takes priority if set)
`POSTGRES_HOST`	Yes*	`localhost`	PostgreSQL hostname
`POSTGRES_PORT`	No	`5432`	PostgreSQL port
`POSTGRES_USER`	Yes*	—	PostgreSQL username
`POSTGRES_PASSWORD`	Yes*	—	PostgreSQL password
`POSTGRES_DB`	Yes*	—	PostgreSQL database name

Note

*Either DATABASE_URL or the individual POSTGRES_* variables must be set.

Redis

Variable	Required	Default	Description
`REDIS_URL`	Yes	—	Redis connection URL (e.g. `redis://localhost:6379`)

Redis must have the RedisJSON module loaded for sync document storage.

Authentication

Variable	Required	Default	Description
`JWT_SECRET`	No	—	Default JWT signing secret

Warning

In production, always use the signing key management system (Admin → Security → Signing Keys) with key rotation instead of a static JWT_SECRET.

Sync Document Cache

Variable	Required	Default	Description
`SYNC_DOC_TTL_SECONDS`	No	`600`	TTL in seconds for hot sync documents in Redis (default: 10 minutes)

Info

When REDIS_URL is available, sync documents use a hybrid Redis + Postgres architecture: Redis as a hot cache for active documents and Postgres as durable storage. The TTL controls how long inactive documents stay in Redis before being evicted. Every read or write refreshes the TTL. See the Architecture page for details on the hybrid storage pattern.

CDC (Change Data Capture)

These configure the connection to your application database — the database whose changes you want to stream in real time. This is separate from the platform's own metadata database.

Variable	Required	Default	Description
`CDC_DATABASE_URL`	No	—	Target application database connection string
`CDC_POLL_INTERVAL_MS`	No	`1000`	CDC polling interval in milliseconds
`CDC_SLOT_NAME`	No	`realtime_cdc_slot`	PostgreSQL logical replication slot name

Info

If CDC_DATABASE_URL is not set, the workers start but CDC is disabled. All other platform features still work.

Admin UI

Variable	Default	Description
`VITE_API_URL`	`http://localhost:3000`	Backend API base URL

Example `.env` File

# Server
NODE_ENV=development
PORT=3000
LOG_LEVEL=debug

# Platform database (Realtime's own metadata)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=realtime
POSTGRES_PASSWORD=realtime_secret
POSTGRES_DB=realtime

# Redis (with RedisJSON module)
REDIS_URL=redis://localhost:6379

# Sync Document Cache (default: 10 minutes)
# SYNC_DOC_TTL_SECONDS=600

# JWT Authentication
JWT_SECRET=your-jwt-secret-here

# Target database (your application DB for CDC monitoring)
CDC_DATABASE_URL=postgresql://myapp:myapp@localhost:5432/myapp
CDC_POLL_INTERVAL_MS=1000
CDC_SLOT_NAME=realtime_cdc_slot

Configuration Validation

The @realtime/shared-config package validates all environment variables at startup using Zod schemas. If a required variable is missing or invalid, the service logs a clear error message and exits.

import { getConfig } from '@realtime/shared-config';

const config = getConfig();
// config.port        → 3000
// config.logLevel    → 'debug'
// config.redis.url   → 'redis://localhost:6379'
// config.postgres.*  → database connection details

Docker Compose

The included docker-compose.yml provides local development infrastructure:

services:
  postgres:
    image: postgres:14-alpine
    environment:
      POSTGRES_USER: realtime
      POSTGRES_PASSWORD: realtime_secret
      POSTGRES_DB: realtime
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis/redis-stack-server:latest
    ports:
      - "6379:6379"

volumes:
  pgdata:

Starting Services

# Start all infrastructure
docker-compose up -d

# Start only PostgreSQL
docker-compose up -d postgres

# Start only Redis
docker-compose up -d redis

# View logs
docker-compose logs -f

# Stop all
docker-compose down

Knex Configuration

The database connection is managed by Knex in packages/database/src/knexfile.ts:

Connection pool: min 2, max 10
Migration table: knex_migrations
Migration directory: packages/database/src/migrations/

Connection priority:

DATABASE_URL (full connection string)
Individual POSTGRES_* variables

Production Considerations

Warning

Never use default passwords or JWT_SECRET values in production.

Set NODE_ENV=production for optimized logging and error handling
Use LOG_LEVEL=info or warn to reduce log volume
Configure Redis with authentication: redis://user:password@host:6379
Use connection pooling for PostgreSQL (the platform uses min 2, max 10 by default)
Set up proper signing keys via the Admin API instead of relying on JWT_SECRET
Use TLS for all database and Redis connections in production