In this tutorial we discuss the installation of Centrifugo on Ubuntu 24.04 | Debian 12 Linux systems. Centrifugo is a real-time messaging server designed to be scalable. Centrifugo is created to work in conjunction with application backend written in any programming language. The software is released under the MIT license. It is a cross platform application – meaning it works on Windows, Linux and MacOS.

Centrifugo runs as separate service and keeps persistent Websocket or SockJS connections from application clients (from web browsers or other environments like iOS/Android apps). When an event needs to sdelivered to your clients in real-time you publish it to Centrifugo API and Centrifugo then broadcasts event to all connected clients interested in this event (i.e. clients subscribed on event channel).

Features of Centrifugo

• Centrifugo is fast and capable to scale to millions of simultaneous connections
• Simple integration with any application – works as separate service
• Simple server API (HTTP or GRPC)
• Client-side libraries for popular frontend environments
• JSON and binary Protobuf Websocket client protocol based on strict schema
• SockJS polyfill for web browsers without Websocket support
• User authentication with JWT or over connection request proxy to configured HTTP endpoint
• Proper connection management and expiration control
• Various types of channels: private, user-limited
• Various types of subscriptions: client-side or server-side
• Transform RPC calls over WebSocket/SockJS to configured HTTP endpoint call
• Presence information for channels (show all active clients in channel)
• History information for channels (last messages published into channel)
• Join/leave events for channels (client goes online/offline)
• Automatic recovery of missed messages between client reconnects over configured retention period
• Built-in administrative web panel
• Ready to deploy (Docker, RPM/DEB packages, automatic Let’s Encrypt TLS certificates, Prometheus/Graphite monitoring)

Install Centrifugo on Ubuntu 24.04 | Debian 12

Centrifugo server is written in Go language around Centrifuge library. In this section we install Centrifugo on your Ubuntu or Debian system from binaries.

Install curl utility if not already present in the system:

sudo apt update -y && sudo apt install curl

Method 1: Binary installation from APT repository

Every time a new Centrifugo is released it is uploaded as rpm and deb packages on packagecloud.io.

Run the command below to configure Centrifugo APT package repository.

curl -s https://packagecloud.io/install/repositories/FZambia/centrifugo/script.deb.sh | sudo bash

Expected output from command execution:

Detected operating system as debian/bookworm.
Checking for curl...
Detected curl...
Checking for gpg...
Detected gpg...
Detected apt version as 2.6.1
Running apt-get update... done.
Installing debian-archive-keyring which is needed for installing 
apt-transport-https on many Debian systems.
Installing apt-transport-https... done.
Installing /etc/apt/sources.list.d/FZambia_centrifugo.list...done.
Importing packagecloud gpg key... Packagecloud gpg key imported to /etc/apt/keyrings/FZambia_centrifugo-archive-keyring.gpg
done.
Running apt-get update... done.

The repository is setup! You can now install packages.s

Update package index:

sudo apt update -y

Then install Centrifugo on Ubuntu 24.04 | Debian 12:

$ sudo apt install centrifugo
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following packages were automatically installed and are no longer required:
  linux-image-6.1.0-25-amd64 linux-image-6.1.0-30-amd64
Use 'sudo apt autoremove' to remove them.
The following NEW packages will be installed:
  centrifugo
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
Need to get 31.5 MB of archives.
After this operation, 66.1 MB of additional disk space will be used.
Get:1 https://packagecloud.io/FZambia/centrifugo/debian bookworm/main amd64 centrifugo amd64 6.1.0-0 [31.5 MB]
Fetched 31.5 MB in 18s (1,757 kB/s)                                                                                                              
Selecting previously unselected package centrifugo.
(Reading database ... 163360 files and directories currently installed.)
Preparing to unpack .../centrifugo_6.1.0-0_amd64.deb ...
Unpacking centrifugo (6.1.0-0) ...
Setting up centrifugo (6.1.0-0) ...

Method 2: Manual installation from github releases

Start by downloading the latest release for your operating system:

curl -s  https://api.github.com/repos/centrifugal/centrifugo/releases/latest | grep browser_download_url |  cut -d '"' -f 4 | grep '\linux_amd64.tar.gz' | wget -i -

Extract the file downloaded:

tar xvf centrifugo_*_linux_amd64.tar.gz

Move extracted binary file to /usr/local/bin directory:

sudo mv centrifugo /usr/local/bin

Confirm successful installation by checking the software version:

$ centrifugo version
Centrifugo v6.1.0 (Go version: go1.24.1)

Configure Centrifugo Messaging Server on Ubuntu 24.04 | Debian 12

Centrifugo server node requires configuration file with some secret keys. You can run genconfig command which generates minimal required configuration file:

$ centrifugo genconfig

This command will generate secret keys automatically and creates configuration file config.json in your current directory:

$ cat config.json
{
  "client": {
    "token": {
      "hmac_secret_key": "Sk9Llz2YEApH_H4JpXqFmiwlq0AMGq_26ZOW0OAe48hcd3lnqeYuKoxR-GMx7Anz5VqU8dRfsK9lqBgytjZZhw"
    },
    "allowed_origins": []
  },
  "admin": {
    "enabled": false,
    "password": "VREXim0kJoqVPwOKLW3Eww",
    "secret": "nI1RKnY-JX42p5ictDCXelTX2qU0PF9DB6HrTxDBFEIvhmGbnC5V4LfJlasBIAF8l_aIcgQuAT6l16B1KShu1Q"
  },
  "http_api": {
    "key": "a5Gem5CSqbTUBcP1X4f5tgaiX5rNmtBNhBzxPBUt9pE7opy3xSUE3eNlY_yw2T2dLu7TjHbTuaXvN9GxaaSr3A"
  }
}

Change the value of admin:enabled to true:

"admin": {
    "enabled": true,
    "password": "VREXim0kJoqVPwOKLW3Eww",
    "secret": "nI1RKnY-JX42p5ictDCXelTX2qU0PF9DB6HrTxDBFEIvhmGbnC5V4LfJlasBIAF8l_aIcgQuAT6l16B1KShu1Q"

Then copy configuration file to /etc directory:

sudo mkdir /etc/centrifugo
sudo mv config.json /etc/centrifugo/config.json

Create Systemd Service Unit:

$ sudo vim /etc/systemd/system/centrifugo.service
[Unit]
Description=Centrifugo Websocket Server
After=network.target syslog.target
 
[Service]
LimitNOFILE=30000
ExecStartPre=/usr/bin/centrifugo checkconfig --config /etc/centrifugo/config.json
ExecStart=/usr/bin/centrifugo --config /etc/centrifugo/config.json
ExecReload=/bin/kill -HUP $MAINPID
ExecStop=/bin/kill -SIGTERM $MAINPID
TimeoutStopSec=5
KillMode=control-group
RestartSec=2
Restart=always
SyslogIdentifier=centrifugo
 
[Install]
WantedBy=multi-user.target
Alias=centrifugo.service

Reload systemd units:

sudo systemctl daemon-reload

Start and enable centrifugo service:

sudo systemctl start centrifugo
sudo systemctl enable centrifugo

Check service status:

$ sudo systemctl status centrifugo
● centrifugo.service - Centrifugo Websocket Server
     Loaded: loaded (/etc/systemd/system/centrifugo.service; enabled; preset: enabled)
     Active: active (running) since Thu 2025-03-20 18:04:41 EAT; 11s ago
    Process: 4215 ExecStartPre=/usr/bin/centrifugo checkconfig --config /etc/centrifugo/config.json (code=exited, status=0/SUCCESS)
   Main PID: 4220 (centrifugo)
      Tasks: 7 (limit: 7032)
     Memory: 50.7M
        CPU: 307ms
     CGroup: /system.slice/centrifugo.service
             └─4220 /usr/bin/centrifugo --config /etc/centrifugo/config.json

Mar 20 18:04:41 debian systemd[1]: Starting centrifugo.service - Centrifugo Websocket Server...
Mar 20 18:04:41 debian systemd[1]: Started centrifugo.service - Centrifugo Websocket Server.
Mar 20 18:04:41 debian centrifugo[4220]: {"level":"info","path":"/etc/centrifugo/config.json","time":"2025-03-20T18:04:41+03:00","message":"using>
Mar 20 18:04:41 debian centrifugo[4220]: {"level":"info","time":"2025-03-20T18:04:41+03:00","message":"maxprocs: leaving gomaxprocs=2: cpu quota >
Mar 20 18:04:41 debian centrifugo[4220]: {"level":"info","version":"6.1.0","runtime":"go1.24.1","pid":4220,"gomaxprocs":2,"engine":"memory","time>
Mar 20 18:04:41 debian centrifugo[4220]: {"level":"info","engine_type":"memory","time":"2025-03-20T18:04:41+03:00","message":"initializing redis >
Mar 20 18:04:41 debian centrifugo[4220]: {"level":"info","time":"2025-03-20T18:04:41+03:00","message":"explicit broker not provided, using the on>
Mar 20 18:04:41 debian centrifugo[4220]: {"level":"info","time":"2025-03-20T18:04:41+03:00","message":"explicit presence manager not provided, us>
Mar 20 18:04:41 debian centrifugo[4220]: {"level":"info","algorithms":"HS256, HS384, HS512","time":"2025-03-20T18:04:41+03:00","message":"enabled>
Mar 20 18:04:41 debian centrifugo[4220]: {"level":"info","time":"2025-03-20T18:04:41+03:00","message":"serving websocket, api endpoints on :8000"}

The admin dashboard will bind to port 8000:

$ sudo ss -tunelp | grep 8000
tcp   LISTEN 0      4096               *:8000             *:*    users:(("centrifugo",pid=4220,fd=3)) ino:30931 sk:b cgroup:/system.slice/centrifugo.service v6only:0 <->   

To stop the service you’ll run:

sudo systemctl stop centrifugo

To restart use the command:

sudo systemctl restart centrifugo

Access Centrifugo web admin console visiting:

http://server_ip_or_hostname:8000

Use the credentials in:

• admin_password: This is a password to log into admin web interface.
• admin_secret: This is a secret key for authentication token set on successful login.

Refer to the following guide for how to secure your Centrifugo server using TLS/SSL:

• Using Self signed certificates and Automatic certificates

Here is a sample updated configuration using Let’s Encrypt SSL certificates:

$ cat /etc/centrifugo/config.json
{
  "v3_use_offset": true,
  "token_hmac_secret_key": "67141ef4-712e-4639-b690-9f9d7b2ab329",
  "admin_password": "ace98706-d844-4c80-970d-883df38cff7c",
  "admin_secret": "d4ae82e2-63a6-441e-a773-cafad60d77b2",
  "api_key": "2c4914d8-a2fd-44b6-a8d3-e87cbfaed9ab",
  "allowed_origins": [],
  "tls_autocert": true,
  "tls_autocert_host_whitelist": "messaging.example.com",
  "tls_autocert_cache_dir": "/tmp/certs",
  "tls_autocert_email": "[email protected]",
  "tls_autocert_http": true,
  "tls_autocert_http_addr": ":80"
}

Where:

• tls_autocert: Tells Centrifugo that you want automatic certificate handling using ACME provider.
• tls_autocert_host_whitelist: is a string with your app domain address. This can be comma-separated list.
• tls_autocert_email: an email address ACME provider will send notifications about problems with your certificates.
• tls_autocert_http: is an option to handle http_01 ACME challenge on non-TLS port.
• tls_autocert_http_addr: can be used to set address for handling http_01 ACME challenge (default is :80)

You’ll need to restart centrifugo service when a change is made in the configuration file:

sudo systemctl restart centrifugo

You’ll then access the web server using https and domain name instead of an IP address, example:

https://messaging.example.com:8000

Login with admin_password value:

Check by running:

$ cat /etc/centrifugo/config.json | jq
{
  "client": {
    "token": {
      "hmac_secret_key": "Sk9Llz2YEApH_H4JpXqFmiwlq0AMGq_26ZOW0OAe48hcd3lnqeYuKoxR-GMx7Anz5VqU8dRfsK9lqBgytjZZhw"
    },
    "allowed_origins": []
  },
  "admin": {
    "enabled": true,
    "password": "VREXim0kJoqVPwOKLW3Eww",
    "secret": "nI1RKnY-JX42p5ictDCXelTX2qU0PF9DB6HrTxDBFEIvhmGbnC5V4LfJlasBIAF8l_aIcgQuAT6l16B1KShu1Q"
  },
  "http_api": {
    "key": "a5Gem5CSqbTUBcP1X4f5tgaiX5rNmtBNhBzxPBUt9pE7opy3xSUE3eNlY_yw2T2dLu7TjHbTuaXvN9GxaaSr3A"
  }
}

You’ll then access admin dashboard:

Read more on the Centrifugo documentation pages.

• How To Install Suricata on Debian 12 (Bookworm)
• Take Screenshots on Ubuntu/Debian Using Flameshot
• Install VSCodium on Ubuntu|Debian|Linux Mint