Centrifugo on a VPS: Self-Hosted Real-Time Server

Centrifugo sits between your application and its users. Your backend — Laravel, Django, Express, Rails or anything else — keeps no connection open: it signs a token for each user, then publishes messages with a plain HTTP call. Centrifugo maintains the WebSocket connections of browsers and mobile apps, and delivers each message to the subscribers of the relevant channel.

This split has a concrete benefit: your application stays stateless and easy to deploy, and the real-time part fits in a single Go binary that uses a few tens of MB of RAM at rest.

An Ubuntu 24.04 VPS with 1 GB of RAM and 10 GB of disk, Docker and the Compose plugin installed, and a subdomain pointing to the VPS, for example rt.example.com. HTTPS is not optional: a site served over HTTPS can only open wss:// connections, and your API key must never travel in clear text.

A WebSocket connection starts with an HTTP request asking to switch protocols. nginx must forward that request, and must not cut a connection that stays quiet for a few minutes. In the server block of your subdomain, with a Let's Encrypt certificate:

location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_read_timeout 3600s;
}

After nginx -t and a reload, https://rt.example.com shows the console login screen.

Publishing means sending a JSON object to a channel. Any language that can make an HTTP request will do:

curl -X POST https://rt.example.com/api/publish \
  -H "X-API-Key: $ENCRYPTION_KEY" \
  -d '{"channel": "commandes", "data": {"id": 1042, "statut": "payee"}}'

The {"result":{}} response confirms the message was accepted. Without the X-API-Key header, or with a wrong key, Centrifugo answers 401.

A browser only connects with a JWT signed by your backend with ENCRYPTION_KEY_HEX64. The sub claim carries the user ID, exp the expiry date, and channels the list of channels the user is subscribed to automatically. Example in Python:

import time, jwt  # pip install pyjwt

def centrifugo_token(user_id: str) -> str:
    claims = {"sub": user_id, "exp": int(time.time()) + 3600, "channels": ["commandes"]}
    return jwt.encode(claims, ENCRYPTION_KEY_HEX64, algorithm="HS256")

Expose this function behind an authenticated route of your application: only a user logged in to your app should be able to get a token.

The settings of this installation are deliberately closed. A browser can neither subscribe to a channel on its own nor publish to it: it only receives the channels listed in the channels claim of its token. Your backend decides, each time it issues a token, who listens to what — a customer only sees their own orders, a support agent only their team's queue.

For a chat, publishing therefore goes through your backend as well: the browser sends the message to your application, which validates it, stores it in the database, then publishes it through the API. This detour costs a few milliseconds and keeps you in control of moderation and history.

Finally, give tokens a short lifetime, one hour for example. Instead of passing a fixed token, let the SDK ask your application for a new one when it expires:

const client = new Centrifuge('wss://rt.example.com/connection/websocket', {
  getToken: async () => {
    const res = await fetch('/realtime/token', { credentials: 'include' });
    return (await res.json()).token;
  },
});

The /realtime/token route belongs to your application; it checks the user's session before signing anything.

On the client side, the official centrifuge SDK (npm) opens the connection and delivers the messages:

import { Centrifuge } from 'centrifuge';

const client = new Centrifuge('wss://rt.example.com/connection/websocket', {
  token: tokenFromYourBackend,
});
client.on('publication', (ctx) => console.log(ctx.channel, ctx.data));
client.connect();

If the connection fails, check the logs first (docker compose logs centrifugo). The message “request Origin is not authorized” means your site's origin is missing from CENTRIFUGO_CLIENT_ALLOWED_ORIGINS; “invalid token” points to a badly signed or expired token.

Open https://rt.example.com and enter ADMIN_PASSWORD: the console does not ask for a username. It shows the node version, the number of connected clients and users, and lets you send API commands — publish a test message, list active channels — without writing code. It is the fastest way to check that a message goes out before looking for the fault in the browser.

This guide uses the memory engine: a single node, with no dependency. It suits most applications, and a modest VPS already holds a large number of simultaneous connections, hence the raised open-file limit in docker-compose.yml. The day one node is no longer enough, Centrifugo can spread the load across several nodes linked by Redis. To update, change the image tag after reading the release notes, then run docker compose pull && docker compose up -d; connections come back on their own, as the client SDKs reconnect automatically.