Centrifugo

intermediate

Scalable real-time messaging server.

Overview

Centrifugo is an open-source real-time messaging server developed by Centrifugal organization that acts as a language-agnostic WebSocket server and message broker. Built in Go for high performance and low latency, Centrifugo handles real-time communication patterns like pub/sub messaging, live chat, notifications, and collaborative features without requiring developers to implement complex WebSocket handling in their backend applications. The server supports multiple transport protocols including WebSocket, Server-Sent Events, HTTP streaming, and SockJS fallback for maximum client compatibility. This Docker deployment creates a production-ready Centrifugo instance with configurable authentication, channel management, and administrative controls. The container exposes both the client connection endpoints and administrative web interface on port 8000, with external configuration file mounting for flexible channel definitions and namespace rules. Environment variables handle sensitive authentication secrets while the JSON configuration file defines channel permissions, connection policies, and real-time messaging behaviors. This stack is ideal for developers building real-time applications who want to offload WebSocket complexity to a dedicated messaging layer, startups requiring scalable chat or notification systems, and enterprises needing reliable real-time data streaming with proper access controls. Centrifugo's stateless design and client SDK ecosystem make it particularly valuable for teams using different programming languages while maintaining consistent real-time messaging capabilities.

Key Features

Multi-protocol transport support with WebSocket, SSE, HTTP streaming, and SockJS fallback
Channel-based pub/sub messaging with configurable namespaces and permission rules
JWT-based authentication with configurable token validation and user presence tracking
Built-in admin web interface for real-time connection monitoring and channel management
Horizontal scaling support with Redis, KeyDB, Tarantool, or NATS as message brokers
Client connection statistics and metrics with Prometheus integration
Message history and recovery mechanisms for reliable message delivery
Private channel subscriptions with server-side authorization callbacks

Common Use Cases

1Real-time chat applications requiring multi-room messaging and user presence
2Live collaborative editing tools like document editors or design platforms
3Financial trading dashboards with live price feeds and order book updates
4Gaming applications needing real-time player updates and match coordination
5IoT dashboards displaying live sensor data and device status monitoring
6Social media platforms with live notifications and activity feeds
7Customer support systems with real-time chat and agent assignment

Prerequisites

Docker and Docker Compose installed with minimum 512MB available memory
Port 8000 available for client connections and admin interface access
Basic understanding of pub/sub messaging patterns and WebSocket protocols
JSON configuration knowledge for defining channels and namespace rules
Client SDK familiarity for your application's programming language
Redis or NATS server access for production scaling beyond single instance

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  centrifugo: 
3    image: centrifugo/centrifugo:latest
4    container_name: centrifugo
5    restart: unless-stopped
6    command: centrifugo -c config.json
7    environment: 
8      CENTRIFUGO_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
9      CENTRIFUGO_ADMIN_SECRET: ${ADMIN_SECRET}
10      CENTRIFUGO_TOKEN_HMAC_SECRET_KEY: ${TOKEN_SECRET}
11    volumes: 
12      - ./config.json:/centrifugo/config.json
13    ports: 
14      - "8000:8000"

.env Template

.env

1ADMIN_PASSWORD=changeme
2ADMIN_SECRET=your-admin-secret
3TOKEN_SECRET=your-token-secret

Usage Notes

1Docs: https://centrifugal.dev/docs/
2API at http://localhost:8000, admin UI at /admin
3Create config.json with channels and namespaces
4Client SDKs: centrifuge-js, centrifuge-go, centrifuge-python
5Supports WebSocket, SSE, HTTP streaming, SockJS fallback
6Scale with Redis or NATS as broker backend

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  centrifugo:
5    image: centrifugo/centrifugo:latest
6    container_name: centrifugo
7    restart: unless-stopped
8    command: centrifugo -c config.json
9    environment:
10      CENTRIFUGO_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
11      CENTRIFUGO_ADMIN_SECRET: ${ADMIN_SECRET}
12      CENTRIFUGO_TOKEN_HMAC_SECRET_KEY: ${TOKEN_SECRET}
13    volumes:
14      - ./config.json:/centrifugo/config.json
15    ports:
16      - "8000:8000"
17EOF
18
19# 2. Create the .env file
20cat > .env << 'EOF'
21ADMIN_PASSWORD=changeme
22ADMIN_SECRET=your-admin-secret
23TOKEN_SECRET=your-token-secret
24EOF
25
26# 3. Start the services
27docker compose up -d
28
29# 4. View logs
30docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/centrifugo/run | bash

Troubleshooting

Connection refused on port 8000: Verify ADMIN_PASSWORD and TOKEN_SECRET environment variables are set
Config file not found error: Ensure config.json exists in current directory with valid JSON syntax
Client authentication failed: Check TOKEN_HMAC_SECRET_KEY matches the secret used for JWT generation
Admin interface shows 'Unauthorized': Verify ADMIN_SECRET environment variable matches client configuration
WebSocket connections dropping: Review channel permissions in config.json and ensure proper namespace configuration
High memory usage with many connections: Configure connection limits and implement Redis broker for horizontal scaling

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

centrifugo

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download