Docs/ Backend as a Service/ Realtime (Centrifugo)

Realtime (Centrifugo)

Real-time WebSocket messaging with channels, presence, and pub/sub.

Creating a Realtime Server

To create a realtime instance:

  1. Navigate to Realtime Servers in the sh0 dashboard.
  2. Click Create Realtime Server.
  3. Enter a name (e.g., "my-app-realtime").
  4. Click Create. sh0 deploys a Centrifugo instance with auto-SSL.

Your realtime server is immediately accessible at wss://<name>.sh0.app/connection/websocket.

Channels

Channels are the primary abstraction in Centrifugo. Clients subscribe to channels and receive messages published to them. Channel names are strings -- you define the naming convention.

Namespaces

Use channel namespaces to group channels with shared configuration. For example, channels named chat:room-1 and chat:room-2 belong to the chat namespace (using : as separator).

Configure namespace-level settings for history retention, presence tracking, and permissions in the Centrifugo configuration.

Presence

Enable presence on a channel to track which users are currently subscribed. Presence information includes client ID and user ID. Useful for:

  • Showing who is online in a chat room.
  • Displaying active collaborators in a document.
  • Tracking viewer count on a live stream.

Publish API

Publish messages from your backend to any channel via the HTTP API:

POST https://<name>.sh0.app/api/publish
Content-Type: application/json
Authorization: apikey <your-api-key>
{
"channel": "chat:room-42",
"data": { "text": "Hello!", "user": "alice" }
}

The API key is generated when you create the realtime server and is visible in the dashboard.

Tip
The publish API is a simple HTTP POST -- call it from any backend language. No WebSocket connection needed from your server.

JavaScript Client

Install the Centrifugo JavaScript client:

npm install centrifuge

Connect and subscribe:

import { Centrifuge } from 'centrifuge';
const client = new Centrifuge(
'wss://my-realtime.sh0.app/connection/websocket'
);
const sub = client.newSubscription('chat:room-42');
sub.on('publication', (ctx) => {
console.log(ctx.data);
});
sub.subscribe();
client.connect();

Authentication

Centrifugo supports JWT-based authentication. When creating the client connection, pass a token:

const client = new Centrifuge(
'wss://my-realtime.sh0.app/connection/websocket',
{ token: jwtToken }
);

The token should contain the user's sub (subject) claim. If you are using the sh0 Auth service (Logto), the access token works directly.

Admin Dashboard

Centrifugo includes a built-in admin dashboard for monitoring your realtime server. Access it at your realtime server's domain. The dashboard shows:

  • Active connections count.
  • Messages per second throughput.
  • Active channels and their subscriber counts.
  • Server node information and health status.
Previous
Authentication (Logto)
Next
Functions (Deno)