# Centrifugo

> Scalable real-time messaging server.

- Category: Message Queues & Brokers
- Difficulty: intermediate
- Components: centrifugo
- Tags: centrifugo, realtime, websocket, pubsub
- Source: https://docker.recipes/messaging/centrifugo

## 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.

## 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

## Use cases

- Real-time chat applications requiring multi-room messaging and user presence
- Live collaborative editing tools like document editors or design platforms
- Financial trading dashboards with live price feeds and order book updates
- Gaming applications needing real-time player updates and match coordination
- IoT dashboards displaying live sensor data and device status monitoring
- Social media platforms with live notifications and activity feeds
- Customer 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

## docker-compose.yml

```yaml
services:
  centrifugo:
    image: centrifugo/centrifugo:latest
    container_name: centrifugo
    restart: unless-stopped
    command: centrifugo -c config.json
    environment:
      CENTRIFUGO_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
      CENTRIFUGO_ADMIN_SECRET: ${ADMIN_SECRET}
      CENTRIFUGO_TOKEN_HMAC_SECRET_KEY: ${TOKEN_SECRET}
    volumes:
      - ./config.json:/centrifugo/config.json
    ports:
      - "8000:8000"
```

## .env

```bash
ADMIN_PASSWORD=changeme
ADMIN_SECRET=your-admin-secret
TOKEN_SECRET=your-token-secret
```

## Usage notes

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

## 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

