Centrifugo Real-Time Messaging Server on AWS 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 instance 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 instance 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

Connecting to your instance

Connect over SSH on port 22 as the default login user for your AMI variant. Use the key pair you selected at launch and the instance's public IP or DNS name.

Prerequisites

An AWS account, an EC2 key pair in your target region, and a VPC with a subnet. Recommended instance type: m5.large (Centrifugo is very light; a couple of GB of RAM is plenty for tens of thousands of connections, and larger types scale the connection count).

Step 1: Launch from the EC2 Console

Find the Centrifugo listing in AWS Marketplace, subscribe, and launch it. In the launch wizard choose your instance type, key pair and subnet, and attach a security group 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 or a load balancer with TLS in front of port 80 for production.

Step 2: Launch from the AWS CLI

AMI_ID="ami-0123456789abcdef0"   # the Centrifugo AMI id in your region
KEY_NAME="my-keypair"; SUBNET_ID="subnet-abc123"; SG_ID="sg-abc123"
aws ec2 run-instances --image-id "$AMI_ID" --instance-type m5.large \
  --key-name "$KEY_NAME" --subnet-id "$SUBNET_ID" --security-group-ids "$SG_ID" \
  --metadata-options 'HttpTokens=required' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=centrifugo-01}]'

Create the security group first with inbound TCP 22 and TCP 80 restricted to your own networks.

Step 3: Connect via SSH

ssh ubuntu@<public-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

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

CENTRIFUGO_ADMIN_PASSWORD=<CENTRIFUGO_ADMIN_PASSWORD>
CENTRIFUGO_API_KEY=<per-instance api key>
CENTRIFUGO_TOKEN_HMAC_SECRET_KEY=<per-instance jwt signing key>
CENTRIFUGO_ADMIN_SECRET=<per-instance admin session secret>
CENTRIFUGO_URL=http://<public-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": "nPGuReDz"
  }
}
[
  {
    "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:

http://<public-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://<public-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

Centrifugo reports version 6.9.1 and the installed component paths:

Centrifugo v6.9.1 (Go version: go1.26.5)
/etc/centrifugo/config.json
/etc/systemd/system/centrifugo.service
/usr/local/bin/centrifugo

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 instance, 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 security group 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 AWS

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