In this tutorial we discuss the installation of Centrifugo on Ubuntu 20.04 | Debian 10 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 delivered 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 20.04 | Debian 10

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
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 Ubuntu/focal.
Checking for curl...
Detected curl...
Checking for gpg...
Detected gpg...
Running apt-get update... done.
Installing apt-transport-https... done.
Installing /etc/apt/sources.list.d/FZambia_centrifugo.list...done.
Importing packagecloud gpg key... done.
Running apt-get update... done.

The repository is setup! You can now install packages.

Update package index:

sudo apt update

Then install Centrifugo on Ubuntu 20.04 | Debian 10

$ sudo apt install centrifugo
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following NEW packages will be installed:
  centrifugo
0 upgraded, 1 newly installed, 0 to remove and 132 not upgraded.
Need to get 11.4 MB of archives.
After this operation, 23.7 MB of additional disk space will be used.
Get:1 https://packagecloud.io/FZambia/centrifugo/ubuntu focal/main amd64 centrifugo amd64 2.8.4-0 [11.4 MB]
Fetched 11.4 MB in 2s (7230 kB/s)
Selecting previously unselected package centrifugo.
(Reading database ... 63399 files and directories currently installed.)
Preparing to unpack .../centrifugo_2.8.4-0_amd64.deb ...
Unpacking centrifugo (2.8.4-0) ...
Setting up centrifugo (2.8.4-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 v2.8.4 (Go version: go1.16.3)

Configure Centrifugo Messaging Server on Ubuntu 20.04 | Debian 10

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
{
  "v3_use_offset": true,
  "token_hmac_secret_key": "66a3adfa-6e9c-4cd6-91eb-23afbaffb36a",
  "admin_password": "1ab1bcb0-e701-4272-b8aa-15e46891fb5f",
  "admin_secret": "b2d235f8-2210-4f44-bc67-33fbe197e78e",
  "api_key": "9d28148e-d682-4a6e-920b-ca5abc7b6ccc",
  "allowed_origins": []
}

Copy configuration file to /etc directory:

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

Create Systemd Service Unit:

sudo tee /etc/systemd/system/centrifugo.service<<EOF
[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 --admin
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
EOF

Reload systemd units

sudo systemctl daemon-reload

Start centrifugo service:

sudo systemctl start centrifugo

Also set the service to start at system boot:

$ sudo systemctl enable centrifugo

Check service status:

$ systemctl status centrifugo
● centrifugo.service - Centrifugo Websocket Server
     Loaded: loaded (/lib/systemd/system/centrifugo.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2021-04-05 10:17:24 UTC; 12s ago
    Process: 15810 ExecStartPre=/usr/bin/centrifugo checkconfig --config (code=exited, status=0/SUCCESS)
   Main PID: 15823 (centrifugo)
      Tasks: 6 (limit: 1137)
     Memory: 7.4M
     CGroup: /system.slice/centrifugo.service
             └─15823 /usr/bin/centrifugo --config --admin

Apr 05 10:17:24 ubuntu centrifugo[15810]:    checkconfig [flags]
Apr 05 10:17:24 ubuntu centrifugo[15810]: Flags:
Apr 05 10:17:24 ubuntu centrifugo[15810]:   -c, --config string   path to config file to check (default "config.json")
Apr 05 10:17:24 ubuntu centrifugo[15810]:   -h, --help            help for checkconfig
Apr 05 10:17:24 ubuntu systemd[1]: Started Centrifugo Websocket Server.
Apr 05 10:17:24 ubuntu centrifugo[15823]: {"level":"info","version":"2.8.4","runtime":"go1.16.3","pid":15823,"engine":"Memory","gomaxprocs":1,"time":"2021-04-05T>
Apr 05 10:17:24 ubuntu centrifugo[15823]: {"level":"info","path":"/--admin","time":"2021-04-05T10:17:24Z","message":"using config file"}
Apr 05 10:17:24 ubuntu centrifugo[15823]: {"level":"warn","time":"2021-04-05T10:17:24Z","message":"consider migrating to offset protocol field, details: https://>
Apr 05 10:17:24 ubuntu centrifugo[15823]: {"level":"warn","time":"2021-04-05T10:17:24Z","message":"config file not found"}
Apr 05 10:17:24 ubuntu centrifugo[15823]: {"level":"info","time":"2021-04-05T10:17:24Z","message":"serving websocket, SockJS, 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=15900,fd=3)) ino:62412 sk:5 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:

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
$ sudo systemctl status centrifugo
● centrifugo.service - Centrifugo Websocket Server
     Loaded: loaded (/lib/systemd/system/centrifugo.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2021-04-05 10:42:00 UTC; 9s ago
    Process: 16307 ExecStartPre=/usr/bin/centrifugo checkconfig --config /etc/centrifugo/config.json (code=exited, status=0/SUCCESS)
   Main PID: 16322 (centrifugo)
      Tasks: 6 (limit: 1137)
     Memory: 7.7M
     CGroup: /system.slice/centrifugo.service
             └─16322 /usr/bin/centrifugo --config /etc/centrifugo/config.json --admin

Apr 05 10:42:00 ubuntu systemd[1]: Starting Centrifugo Websocket Server...
Apr 05 10:42:00 ubuntu systemd[1]: Started Centrifugo Websocket Server.
Apr 05 10:42:00 ubuntu centrifugo[16322]: {"level":"info","version":"2.8.4","runtime":"go1.16.3","pid":16322,"engine":"Memory","gomaxprocs":1,"time":"2021-04-05T>
Apr 05 10:42:00 ubuntu centrifugo[16322]: {"level":"info","path":"/etc/centrifugo/config.json","time":"2021-04-05T10:42:00Z","message":"using config file"}
Apr 05 10:42:00 ubuntu centrifugo[16322]: {"level":"info","time":"2021-04-05T10:42:00Z","message":"serving websocket, SockJS, API, admin endpoints on :8000"}
Apr 05 10:42:00 ubuntu centrifugo[16322]: {"level":"info","time":"2021-04-05T10:42:00Z","message":"serving ACME http_01 challenge on :80"}

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:

You’ll then access admin dashboard:

Read more on the Centrifugo documentation pages.