☁ Relay Cloud handles all configuration for you. No environment variables, no server tuning. Try Relay Cloud →

Configuration

All configuration is done via environment variables.

Environment Variables

Variable	Default	Description
`RELAY_HOST`	`0.0.0.0`	Host to bind
`RELAY_PORT`	`6001`	Port to listen on
`RELAY_APP_ID`	`app`	Default app ID
`RELAY_APP_KEY`	(required)	App authentication key
`RELAY_APP_SECRET`	(required)	App secret for signing
`RELAY_DEBUG`	`false`	Enable debug logging
`RELAY_MAX_CONNECTIONS`	`0` (unlimited)	Max concurrent connections
`RELAY_DASHBOARD_ENABLED`	`true`	Enable web dashboard
`RELAY_DASHBOARD_PATH`	`/dashboard`	Dashboard URL path
`RELAY_HISTORY_ENABLED`	`false`	Enable event history
`RELAY_HISTORY_MAX`	`100`	Max events to store
`RELAY_WEBHOOK_URL`	(empty)	Webhook endpoint URL
`RELAY_WEBHOOK_EVENTS`	(empty)	Events to send to webhook
`RELAY_RATE_LIMIT_ENABLED`	`false`	Enable rate limiting
`RELAY_RATE_LIMIT_MAX`	`100`	Max events per second

Multi-App Configuration

To run multiple apps on a single Relay server, create an apps.json file. Each app gets its own credentials and connection limits, allowing you to isolate tenants or environments on one instance.

Place the file at /etc/relay/apps.json:

[
  {
    "id": "app_1",
    "key": "key-1",
    "secret": "secret-1",
    "max_connections": 1000
  },
  {
    "id": "app_2",
    "key": "key-2",
    "secret": "secret-2",
    "max_connections": 500
  }
]

Note: When using apps.json, the RELAY_APP_KEY and RELAY_APP_SECRET environment variables are ignored. All app credentials are read from the JSON file instead.

Docker Compose

A complete docker-compose.yml example with all common options:

version: '3.8'
services:
  relay:
    image: relayhq/relay:latest
    ports:
      - "6001:6001"
    environment:
      RELAY_APP_KEY: my-key
      RELAY_APP_SECRET: my-secret
      RELAY_DEBUG: "false"
      RELAY_DASHBOARD_ENABLED: "true"
    volumes:
      - ./apps.json:/etc/relay/apps.json
    restart: unless-stopped

☁ Ready to skip the server setup? Relay Cloud gives you a production WebSocket server instantly. Start free, upgrade when you grow. Start Free →