Realtime Platform
Realtime Platform

Getting Started

Installation

Complete installation guide with prerequisites, environment setup, and verification.

This guide walks through every step needed to get the Realtime Platform running from scratch.

Prerequisites

DependencyVersionPurpose
Node.js>= 20.0.0Runtime for all services
pnpm>= 9.0.0Monorepo package manager
PostgreSQL>= 14Platform metadata + CDC source
Redis>= 7.0 (with RedisJSON)Document state, pub/sub, queues

Install Node.js

We recommend using nvm to manage Node.js versions:

nvm install 20
nvm use 20
node --version  # v20.x.x

Install pnpm

npm install -g pnpm@9
pnpm --version  # 9.x.x

PostgreSQL

The included docker-compose.yml starts PostgreSQL automatically:

docker-compose up -d postgres

Redis with RedisJSON

The platform requires Redis with the RedisJSON module for sync document storage.

docker-compose up -d redis

The Docker Compose file uses redis/redis-stack-server which includes RedisJSON.

Clone the Repository

git clone <repo-url> realtime
cd realtime

Install Dependencies

pnpm install

This installs dependencies for all packages and apps in the monorepo. pnpm's workspace protocol ensures shared dependencies are hoisted efficiently.

Environment Configuration

Copy the example environment file:

cp .env.example .env

Required Variables

# PostgreSQL (platform metadata database)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=realtime
POSTGRES_PASSWORD=realtime_secret
POSTGRES_DB=realtime

# Redis
REDIS_URL=redis://localhost:6379

Optional Variables

# Server
NODE_ENV=development
PORT=3000
LOG_LEVEL=debug

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

# CDC (Change Data Capture) - your application database
CDC_DATABASE_URL=postgresql://user:password@host:5432/your_app_db
CDC_POLL_INTERVAL_MS=1000
CDC_SLOT_NAME=realtime_cdc_slot

# Admin UI
VITE_API_URL=http://localhost:3000

Info

See the full Configuration reference for all variables and their defaults.

Build

Build all packages in dependency order:

pnpm build

Turborepo handles the build graph automatically — shared packages build first, then apps.

Verify Installation

Run Tests

pnpm test

All 221+ tests should pass across 12 packages.

Start the Platform

pnpm dev

Verify each service is running:

ServiceCheckExpected
Backendcurl http://localhost:3000/health{"status":"ok"}
Admin UIOpen http://localhost:5173Login/setup page
WorkersCheck terminal outputWorkers started log

Docker Compose (Full Stack)

The included docker-compose.yml provides PostgreSQL and Redis for local development:

services:
  postgres:
    image: postgres:14-alpine
    environment:
      POSTGRES_USER: realtime
      POSTGRES_PASSWORD: realtime_secret
      POSTGRES_DB: realtime
    ports:
      - "5432:5432"

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

Start both services:

docker-compose up -d

Monorepo Structure

After installation, the workspace contains:

realtime/
├── apps/
│   ├── backend/          # Express API + Socket.IO server
│   ├── workers/          # Background workers (CDC, webhooks, etc.)
│   ├── admin-ui/         # React management dashboard
│   └── docs/             # This documentation site
├── packages/
│   ├── shared-types/     # TypeScript interfaces
│   ├── shared-utils/     # Common utilities
│   ├── shared-config/    # Environment config (Zod)
│   ├── observability/    # Logging + metrics
│   ├── redis-layer/      # Redis client + pub/sub
│   ├── auth/             # JWT + permissions
│   ├── event-router/     # Event normalization + routing
│   ├── topic-registry/   # Topic CRUD + validation
│   ├── schema-registry/  # Schema versioning + compatibility
│   ├── metrics/          # Prometheus metrics
│   ├── database/         # Knex migrations + connection
│   └── sdk/              # Client SDK
├── docker-compose.yml
├── turbo.json
└── pnpm-workspace.yaml

Troubleshooting