Service: Centrifugo - EyevinnOSC/community GitHub Wiki

Centrifugo

Centrifugo (serviceId centrifugal-centrifugo) is an open-source (Apache-2.0) real-time messaging server that delivers messages to browser, mobile and server-side clients over WebSocket, SSE, HTTP-streaming and WebTransport. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance.

What it can do

  • Push messages to connected clients in real time: live feeds, notifications, chat, collaborative editing, multiplayer games.
  • Authenticate clients with JWT connection tokens signed with a shared HMAC secret.
  • Accept publish requests from any backend over an HTTP/gRPC server API protected by an API key.
  • Provide an embedded admin web UI for monitoring channels and connections.
  • Scale horizontally across several Centrifugo nodes by connecting a Redis-compatible store such as Valkey.

Creating an instance

Find the id with list-available-services, read the options with get-service-schema, then call create-service-instance with serviceId: "centrifugal-centrifugo". The instance name must be alphanumeric and at most 20 characters. No other OSC service is required; add a Valkey instance (valkey-io-valkey) only if you want horizontal scaling, and confirm it is running before creating Centrifugo.

{
  "name": "mycentrifugo",
  "TokenHmacSecretKey": "{{secrets.centrifugotoken}}",
  "AdminPassword": "{{secrets.centrifugoadmin}}",
  "ApiKey": "{{secrets.centrifugoapikey}}"
}

Create the secrets first with create-service-secret (serviceId centrifugal-centrifugo, name, value). Use wait-for-service-ready or get-instance-status to confirm the instance is running, and describe-service-instance to read its URL and any generated credentials.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
TokenHmacSecretKey Yes string, sensitive Secret key used to verify the HMAC signature of the JWT tokens that clients present when connecting. Your backend signs connection tokens with the same key. Can be generated by the system if left empty.
AdminPassword Yes string, sensitive Password for the embedded admin web UI. Can be generated by the system if left empty.
ApiKey No string, sensitive Key that authenticates requests to the HTTP and gRPC server API (for example publishing). Your backend sends it in the X-API-Key header. Recommended for production.
RedisUrl No string, sensitive Connection URL of a Redis or Redis-compatible server (Redis, Redis Cluster, Valkey, KeyDB, DragonflyDB), for example redis://:password@host:6379. When set, multiple Centrifugo instances share state and can scale horizontally.
AllowedOrigins No string Origins allowed to connect from browsers. The catalog gives no further description or format.

TokenHmacSecretKey, AdminPassword, ApiKey and RedisUrl are sensitive: store them as service secrets and pass them as {{secrets.NAME}}, which only works as the entire field value. Overwriting a secret does not restart a running instance.

Using the instance

Admin UI

The admin web UI is served at the instance URL (https://<name>.centrifugal-centrifugo.auto.prod-se.osaas.io/). There is no username; sign in with the AdminPassword. Use it to monitor channels, active connections and message history.

Connecting clients

Official client libraries exist for JavaScript, React Native, Go, Python, Swift, Dart and more. Your backend generates a JWT connection token signed with TokenHmacSecretKey:

// Backend (Node.js)
const jwt = require('jsonwebtoken');
const token = jwt.sign(
  { sub: 'user123', exp: Math.floor(Date.now() / 1000) + 3600 },
  process.env.CENTRIFUGO_TOKEN_SECRET
);
// Browser
import { Centrifuge } from 'centrifuge';

const client = new Centrifuge('wss://mycentrifugo.centrifugal-centrifugo.auto.prod-se.osaas.io/connection/websocket', {
  token: '<token-from-backend>'
});

const sub = client.newSubscription('news');
sub.on('publication', (ctx) => console.log(ctx.data));
sub.subscribe();
client.connect();

Publishing from your backend

Use the HTTP API with the ApiKey you configured:

curl -X POST https://mycentrifugo.centrifugal-centrifugo.auto.prod-se.osaas.io/api/publish \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"channel": "news", "data": {"text": "Breaking news!"}}'

Scaling with Valkey

  1. Create a Valkey instance and wait until it is running.
  2. Build its connection URL (format redis://:password@host:6379) from the address, port and password in describe-service-instance.
  3. Set RedisUrl (as a secret reference) when creating, or with update-service-instance on, the Centrifugo instance.

All nodes then share channel presence and message history through Valkey.

CLI

osc create centrifugal-centrifugo mycentrifugo \
  -o TokenHmacSecretKey="{{secrets.centrifugo-token-secret}}" \
  -o AdminPassword="{{secrets.centrifugo-admin-pw}}" \
  -o ApiKey="{{secrets.centrifugo-api-key}}"

Resources

⚠️ **GitHub.com Fallback** ⚠️