Skip to content
Roomful

Self-Host Deployment Checklist

Roomful Relay production deployment checklist. Use this when deploying the relay server in a self-hosted environment.

Prerequisites

Section titled “Prerequisites”
  • Node.js 20+ runtime
  • PostgreSQL 14+ (for management store + usage events)
  • Redis 7+ (optional, for multi-instance coordination)
  • Docker & Docker Compose (recommended for production)
  • Domain name + TLS certificate (for WSS/WSS secure connections)
  • Monitoring system (e.g. Prometheus + Grafana, Datadog)

Installation

Section titled “Installation”
  • Pull the relay Docker image or clone the repository
  • Copy .env.production and fill in required values
  • Run database migrations
  • Verify health endpoint responds: GET /health → {"status":"ok"}

Configuration

Section titled “Configuration”

Required

Section titled “Required”
  • Set PORT or ROOMFUL_RELAY_PORT (default: 8787)
  • Set HOST (default: 127.0.0.1 — use 0.0.0.0 for container)
  • Set ROOMFUL_AUTH_SECRET — a strong random string for JWT signing
  • Configure ROOMFUL_DATABASE_URL for PostgreSQL management store
Section titled “Optional but recommended”
  • Set ROOMFUL_REDIS_URL for multi-instance coordination
  • Configure ROOMFUL_MAX_ROOMS, ROOMFUL_MAX_CONNECTIONS, ROOMFUL_MAX_ROOM_SIZE
  • Enable management API with --management-api flag or ROOMFUL_MANAGEMENT_API=true
  • Set ROOMFUL_CORS_ORIGIN for browser client access
  • Configure rate limits: ROOMFUL_MESSAGE_RATE_LIMIT, ROOMFUL_MESSAGE_RATE_INTERVAL_MS

Security

Section titled “Security”
  • Use strong random AUTH_SECRET (min 32 chars)
  • Enable JWT authentication for peer connections
  • Restrict CORS origin to your application domain
  • Run behind a reverse proxy (nginx, Caddy) for TLS termination
  • Use WSS:// protocol (WSS via reverse proxy)
  • Keep PostgreSQL/Redis credentials out of version control
  • Regular security updates for Node.js, PostgreSQL, Redis

Monitoring

Section titled “Monitoring”
  • Health check: GET /health
  • Track relay metrics: active connections, room count, message throughput
  • Set up log aggregation (relay logs to stdout)
  • Configure alerts for: connection drops, high latency, resource usage

Backup

Section titled “Backup”
  • Schedule regular PostgreSQL backups (management store + usage events)
  • Test backup restoration process
  • Document recovery procedures

Scaling

Section titled “Scaling”
  • Horizontal scaling: add relay instances behind a load balancer
  • Enable Redis coordination for cross-instance room synchronization
  • Connection pooling for PostgreSQL (relay-side)
  • Consider connection limits per instance

Production Readiness

Section titled “Production Readiness”
  • Load testing completed with expected concurrent users
  • Rate limiting configured for production traffic
  • TLS termination properly configured
  • Logging level set to appropriate level (info/warn/error)
  • Resource limits configured in Docker/container orchestration