Centrifugo — Scalable Real-Time Messaging Server
Overview
Centrifugo sits between your backend and your clients. The backend publishes to named channels through the server API (/api/publish, authenticated with an API key); clients connect with a JWT signed by your backend and subscribe to channels. Features: namespaces with per-channel options, presence, join/leave events, history with automatic recovery after reconnect, and Redis or NATS engines for several nodes. This skill targets Centrifugo v6 (6.9.7 checked, October 2026). v6 restructured the config: keys that were flat in v5 (token_hmac_secret_key, api_key, allowed_origins, namespaces) now live under client.token.hmac_secret_key, http_api.key, client.allowed_origins and channel.namespaces. SockJS and the Tarantool engine were removed. The official site offers a converter for v5 configs.
Instructions
1. Install and generate a config
# binary: download the release archive and verify it against centrifugo_<version>_checksums.txt
sha256sum -c --ignore-missing centrifugo_6.9.7_checksums.txt
./centrifugo genconfig -c config.json # writes random token key, API key, admin password
./centrifugo checkconfig -c config.json
./centrifugo -c config.json # listens on :8000
Docker alternative: docker run --rm -p 127.0.0.1:8000:8000 -v "$PWD/config.json:/centrifugo/config.json" centrifugo/centrifugo:v6 centrifugo --config=config.json.
2. Configure namespaces
A channel chat:room-42 takes its options from the namespace chat; channels without a namespace use channel.without_namespace. Almost every permission is off by default, so enable what the client needs.
{
"client": {
"token": { "hmac_secret_key": "set-via-CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY" },
"allowed_origins": ["https://shopfront.io"]
},
"http_api": { "key": "set-via-CENTRIFUGO_HTTP_API_KEY" },
"admin": { "enabled": true, "password": "from-env", "secret": "from-env" },
"channel": {
"namespaces": [
{
"name": "chat",
"presence": true, "join_leave": true,
"history_size": 100, "history_ttl": "300s", "force_recovery": true,
"allow_subscribe_for_client": true,
"allow_presence_for_subscriber": true,
"allow_history_for_subscriber": true
},
{
"name": "notifications",
"history_size": 50, "history_ttl": "24h",
"allow_user_limited_channels": true
}
]
}
}
Every key can also be an environment variable: CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY, CENTRIFUGO_HTTP_API_KEY, CENTRIFUGO_CHANNEL_NAMESPACES (a JSON array). Keep secrets in the environment, not in git.
3. Backend: issue tokens and publish
import jwt from "jsonwebtoken";
// connection token: `sub` is the user id; expire it and let the client refresh
export function connectionToken(userId: string) {
return jwt.sign({ sub: userId }, process.env.CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY!, { expiresIn: "1h" });
}
export async function publish(channel: string, data: unknown) {
const res = await fetch("http://localhost:8000/api/publish", {
method: "POST",
headers: { "Content-Type": "application/json", Authorization: `apikey ${process.env.CENTRIFUGO_HTTP_API_KEY}` },
body: JSON.stringify({ channel, data }),
});
const body = await res.json();
if (body.error) throw new Error(`centrifugo ${body.error.code}: ${body.error.message}`);
}
The API replies {"result":{"offset":1,"epoch":"..."}} on success and {"error":{"code":102,"message":"unknown channel"}} for a namespace that is not configured. Other useful methods: /api/history, /api/presence, /api/broadcast (one payload, many channels), /api/disconnect, /api/info. A quick token for testing: ./centrifugo gentoken -c config.json -u alice.
4. Browser client
import { Centrifuge } from "centrifuge"; // npm install centrifuge
const client = new Centrifuge("wss://rt.shopfront.io/connection/websocket", {
getToken: () => fetch("/api/realtime-token").then(r => r.text()), // called on connect and refresh
});
const sub = client.newSubscription("chat:room-42");
sub.on("publication", ctx => console.log(ctx.data)); // { user: "Alice", text: "Hello!" }
sub.on("join", ctx => console.log(`${ctx.info.user} joined`));
sub.subscribe();
client.connect();
const presence = await sub.presence(); // after subscribed
const history = await sub.history({ limit: 50 });
Personal channels use the # form: notifications:#user-123 can be subscribed only by the user whose sub is user-123, and only when the namespace sets allow_user_limited_channels.
Examples
Example 1: Live order notifications
User request: "Tell the customer in the browser when their order ships."
Enable the notifications namespace above, subscribe the page to notifications:#<userId>, and from the order service run await publish("notifications:#user-123", { type: "order_shipped", orderId: "ORD-4561" }). The page's publication handler fires within milliseconds; if the user was offline for a minute, recovery replays missed messages from history.
Example 2: Chat room with presence
User request: "Add a chat room page that shows who is online."
Use the chat namespace, subscribe to chat:room-42, render Object.values((await sub.presence()).clients), and update the list on join/leave. A message is sent by the backend (after checking membership) with publish("chat:room-42", { user: "Alice", text: "Hello!" }).
Guidelines
- Publish from your backend; do not let browsers publish unless you have enabled
allow_publish_for_client and accept unvalidated input. Use the connect/subscribe/publish proxies when the backend must approve each action.
- Never leave
allowed_origins empty or * in production. Do not expose the HTTP API, admin and Prometheus endpoints to the internet: put the API on the internal port or behind a firewall.
- The HMAC secret and API key must be long and random (
genconfig does this); rotate them if leaked. Short-lived tokens plus getToken limit the damage of a stolen token.
- Presence and join/leave cost extra memory and messages: enable them only on channels that need them.
- History is in memory by default and lost on restart. With more than one node use the Redis or NATS engine, otherwise nodes do not share channels.
/api/publish returning HTTP 200 does not mean success: check the error field.- v5 configs and v5 environment variables do not work unchanged on v6; convert them and test before deploying.