Centrifugo on Ubuntu 24.04 on Azure User Guide

Overview

Centrifugo is a scalable, open source real time messaging server. It keeps persistent connections open to your online users over WebSocket, Server Sent Events, HTTP streaming and other transports, and instantly delivers messages to everyone subscribed to a channel. Because it follows a language agnostic publish and subscribe model, you keep your real time transport layer completely separate from your application: your backend publishes events through a simple server side HTTP API, and your users connect with short lived JSON Web Tokens. It is a single Go binary, so it stays lightweight and starts instantly.

The cloudimg image installs Centrifugo 6.9.1 and puts it behind an nginx reverse proxy that binds the server to loopback and already handles WebSocket upgrades. The appliance is secure by default: there is no default login. On first boot centrifugo-firstboot.service generates four unique per VM secrets, injects them into the configuration, and writes them to a root only file at /root/centrifugo-info.txt. Nothing is baked into the image.

What is included:

• Centrifugo 6.9.1 single Go binary (/usr/local/bin/centrifugo)
• centrifugo.service running as centrifugo, bound to loopback 127.0.0.1:8000
• nginx.service reverse proxy on TCP 80, TLS ready, with WebSocket upgrade configured
• centrifugo-firstboot.service generating four per VM secrets on first boot
• Built in admin web UI for inspecting nodes and channels
• A server HTTP API for publishing, broadcasting, presence and channel history
• A smoke channel namespace pre configured with history, ready to test
• Ubuntu 24.04 LTS base, latest patches, unattended security upgrades enabled
• 24/7 cloudimg support, 24h response SLA

Prerequisites

An active Azure subscription, an SSH key, and a VNet with a subnet. Recommended VM size: Standard_B2s (Centrifugo is very light; 4 GB RAM is plenty for tens of thousands of connections).

Step 1: Deploy from the Azure Portal

Search the Azure Marketplace for Centrifugo, choose the plan, and create the VM. In the networking step attach an NSG that allows inbound TCP 22 (SSH) and TCP 80 (the admin UI, server API and client transports) from your client networks only. Put a TLS reverse proxy in front of port 80 for production.

Step 2: Deploy from the Azure CLI

RG="centrifugo-prod"; LOCATION="eastus"; VM_NAME="centrifugo-01"
GALLERY_IMAGE_ID="/subscriptions/<sub-id>/resourceGroups/azure-cloudimg/providers/Microsoft.Compute/galleries/cloudimgGallery/images/centrifugo-ubuntu-24-04/versions/<version>"
SSH_KEY="$(cat ~/.ssh/id_rsa.pub)"
az group create --name "$RG" --location "$LOCATION"
az network vnet create -g "$RG" --name cf-vnet --address-prefix 10.108.0.0/16 --subnet-name cf-subnet --subnet-prefix 10.108.1.0/24
az network nsg create -g "$RG" --name cf-nsg
az network nsg rule create -g "$RG" --nsg-name cf-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp
az network nsg rule create -g "$RG" --nsg-name cf-nsg --name allow-web --priority 110 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 80 --access Allow --protocol Tcp
az vm create -g "$RG" --name "$VM_NAME" --image "$GALLERY_IMAGE_ID" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name cf-vnet --subnet cf-subnet --nsg cf-nsg --public-ip-sku Standard

Step 3: Connect via SSH

ssh azureuser@<vm-ip>

centrifugo.service, nginx.service and centrifugo-firstboot.service all start automatically on first boot.

Step 4: Verify the Service

sudo systemctl is-active centrifugo nginx centrifugo-firstboot
sudo test -f /var/lib/cloudimg/centrifugo-firstboot.done && echo FIRSTBOOT_DONE
sudo ss -tlnp | grep -E ':80 |:8000 '

Expected output — all three services are active, nginx is bound to the public port 80 and Centrifugo is bound to loopback 127.0.0.1:8000 only:

active
active
active
FIRSTBOOT_DONE
LISTEN 0 4096 127.0.0.1:8000 0.0.0.0:*  users:(("centrifugo",...))
LISTEN 0 511  0.0.0.0:80     0.0.0.0:*  users:(("nginx",...))

Step 5: Get Your Secrets

Centrifugo has no default login. On first boot four unique secrets are generated and written to a root only note: the admin password, the server API key, the client token signing key and the admin session secret. None of them is baked into the image:

sudo cat /root/centrifugo-info.txt
sudo ss -tlnp | grep 8000

The note contains all four secrets and the resolved URL, all unique to this machine:

CENTRIFUGO_ADMIN_PASSWORD=<CENTRIFUGO_ADMIN_PASSWORD>
CENTRIFUGO_API_KEY=<per-VM api key>
CENTRIFUGO_TOKEN_HMAC_SECRET_KEY=<per-VM jwt signing key>
CENTRIFUGO_ADMIN_SECRET=<per-VM admin session secret>
CENTRIFUGO_URL=http://<vm-ip>/

Step 6: Publish a Message with the Server API

Your backend publishes events through the server HTTP API, authenticated with the API key in the X-API-Key header. Publish a message to the pre configured smoke namespace, then read it back from channel history — this is exactly what your application does to push a real time event:

API_KEY=$(sudo grep '^CENTRIFUGO_API_KEY=' /root/centrifugo-info.txt | cut -d= -f2-)
curl -s -H "X-API-Key: $API_KEY" -H 'Content-Type: application/json' \
  --data '{"channel":"smoke:demo","data":{"message":"hello from cloudimg"}}' \
  http://127.0.0.1/api/publish | jq .
curl -s -H "X-API-Key: $API_KEY" -H 'Content-Type: application/json' \
  --data '{"channel":"smoke:demo","limit":5}' \
  http://127.0.0.1/api/history | jq '.result.publications'

The publish returns a stream position, and the history call returns the message you just published:

{
  "result": {
    "offset": 1,
    "epoch": "YDgviNmM"
  }
}
[
  {
    "data": { "message": "hello from cloudimg" },
    "offset": 1
  }
]

Step 7: Log In to the Admin UI

Open the admin web UI in a browser and log in with the admin password from Step 5. The admin UI has no username — only a password:

open http://<vm-ip>/

Step 8: The Status Dashboard

After logging in the Status tab shows live metrics: how many nodes are running, the total number of connected clients and subscriptions, and a per node table with the Centrifugo version, uptime, client count and channel count. This is your at a glance health and scale view:

Step 9: The Actions Console

The Actions tab is a console for calling the server API straight from the browser. Pick a method (Publish, Broadcast, Presence, History, Channels and more), fill in the form, and submit — useful for testing channels and inspecting state without writing any code:

Step 10: Publish from the Console

Set the method to Publish, enter a channel such as smoke:demo, type a small JSON payload, and click PUBLISH. The request and the server response appear below the form, so you can watch a real time message go out live:

Step 11: Connect a Client

Your users connect from the browser (or a mobile or server SDK) over WebSocket, authenticating with a short lived JWT signed with the client token signing key from Step 5. Generate a test token on the server and point a client at the WebSocket endpoint:

# generate a connection JWT for user "alice" (valid for the client SDK)
sudo /usr/local/bin/centrifugo gentoken -c /etc/centrifugo/config.json -u alice
# your browser client then connects to: ws://<vm-ip>/connection/websocket

Official client SDKs are available for JavaScript, Dart, Swift, Java, Python, Go and .NET. Point them at your server's /connection/websocket endpoint and subscribe to a channel to start receiving events.

Step 12: Server Components

/usr/local/bin/centrifugo version
ls /usr/local/bin/centrifugo /etc/centrifugo/config.json /etc/systemd/system/centrifugo.service

Step 13: Managing the Service

sudo systemctl restart centrifugo.service
sudo systemctl is-active centrifugo.service

Centrifugo restarts in well under a second because it is a single binary using the built in in memory engine. The service is hardened with NoNewPrivileges, ProtectSystem=strict and ProtectHome, and writes nothing to disk. Because the engine is in memory, channel history and presence reset on restart — attach Redis in the configuration if you need history to survive a restart or to scale across multiple nodes.

Step 14: Configuration

Centrifugo is configured through /etc/centrifugo/config.json. Useful keys already set by the image:

After editing the file, apply changes with sudo systemctl restart centrifugo.service. Before you connect browser clients from your own web app, set client.allowed_origins to your app's origins so cross origin WebSocket connections are accepted.

Step 15: Add TLS (Optional)

For production, terminate TLS at nginx. Point a DNS record at the VM, then use the packaged nginx with a certificate from Let's Encrypt:

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain>

certbot installs the certificate, rewrites the nginx server block to listen on 443 and sets up automatic renewal. Real time transports run cleanly over the resulting wss:// and https:// endpoints.

Step 16: Security Recommendations

• Restrict the NSG so ports 80 and 22 only reach trusted networks.
• Terminate TLS at nginx (Step 15) so tokens, API keys and messages travel encrypted.
• Set client.allowed_origins to your application's origins so only your web app can open browser WebSocket connections.
• Keep the API key secret — it is the key to publishing on every channel. Rotate it in /etc/centrifugo/config.json and restart if it is ever exposed.
• Use short lived client JWTs signed with the token signing key, so a leaked client token expires quickly.
• Patch the OS monthly with sudo apt-get update && sudo apt-get upgrade; unattended security upgrades are already enabled.

Step 17: Support and Licensing

Centrifugo is distributed under the Apache License 2.0 — no per CPU or per user fee. cloudimg provides commercial support separately.

• Email: support@cloudimg.co.uk
• Website: www.cloudimg.co.uk
• Support hours: 24/7, 24h response SLA

Deploy on Azure

Launch Centrifugo on Ubuntu 24.04 with 24/7 support from cloudimg.

View on Marketplace

Need Help?

Our support team is available 24/7. support@cloudimg.co.uk