Centrifugo is a scalable real-time messaging server. Centrifugo works in conjunction with application backend written in any programming language. It runs as a separate service and keeps persistent Websocket or SockJS connections from application clients. When you need to deliver an event to your clients in real-time, you publish it to Centrifugo API. Centrifugo then broadcasts the event to all connected clients interested in this event (i.e. clients subscribed on the event channel).
In this guide, you will learn will how to install Centrifugo on Ubuntu 20.04 server.
Table of Contents
Prerequisites
- Root access or sudo privileges.
- Ubuntu 20.04 LTS. (21.04 does work with this guide)
- WGET command
sudo apt update && sudo apt upgrade -y \
sudo apt install wget
Download Centrifugo
Ubuntu repositories do not include Centrifugo, so you will need to download the source from its GIT repository. It’s recommended to check the Releases page as the below guide example Centrifugo version may be outdated. Once you have visited the Release page and got the latest link, type the following.
wget https://github.com/centrifugal/centrifugo/releases/download/v2.8.5/centrifugo_2.8.5_linux_amd64.tar.gz
Once the download is completed, extract the downloaded file by typing the following command.
tar -xvzf centrifugo_2.8.5_linux_amd64.tar.gz
Install Centrifugo
Now, you will need to move the Centrifugo binary to the /usr/bin directory:
sudo mv centrifugo /usr/bin
Lastly, you should verify the version to ensure it’s installed and everything is working correctly so far.
centrifugo version
Example output:
~$ centrifugo version
Centrifugo v2.8.5 (Go version: go1.16.4)
Configure Centrifugo
To configure Centrifugo, it’s pretty simple. First, you need to generate the configuration file, but rather, let’s create a directory to keep the configurations files.
sudo mkdir -p /etc/centrifugo && cd /etc/centrifugo
Then you can generate the config file by typing.
sudo centrifugo genconfig
After entering this command, it will generate a config.json file in the directory you have specified.
You can verify the file by typing the following CAT command.
cat config.json
You should get the following output:
:/etc/centrifugo$ cat config.json
{
"v3_use_offset": true,
"token_hmac_secret_key": "4bfd92e6-9526-474a-877b-0730c55f37ea",
"admin_password": "1fe1f1f3-df96-4bfe-b383-bfe7a8408660",
"admin_secret": "5ce4d2cd-2db9-4ad9-a6c6-6c6dfe1160a6",
"api_key": "fcb8ff4f-64be-4918-bb57-711fdfc852cb",
"allowed_origins": []
}
Take note of your “admin password“, as you will need it to log in to the web UI. Saving the entire is recommended.
Create Systemd Service File for Centrifugo
The last part of setting up Centrifugo is creating a Systemd service file. We will use nano text editor for this.
sudo nano /etc/systemd/system/centrifugo.service
Once you have the nano editor and file open, type the following input into the file.
[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
Press CTRL+O, then enter “Y”, which will save the data input into the file, then press CTRL+X to exit the file.
Now you will need to reload the daemon, which is done by the following command.
sudo systemctl daemon-reload
Next, start the system process and while you are it, enable the service on startup if you prefer.
sudo systemctl start centrifugo && sudo systemctl enable centrifugo
Once the service has been started, check the service to make sure all is working well.
systemctl status centrifugo
You should see the following output:
● centrifugo.service - Centrifugo Websocket Server
Loaded: loaded (/etc/systemd/system/centrifugo.service; disabled; vendor preset: enabled)
Active: active (running) since Wed 2021-06-23 00:47:38 PDT; 4s ago
Process: 20356 ExecStartPre=/usr/bin/centrifugo checkconfig --config /etc/centrifugo/config.json (code=exited, status=0/SUCCESS)
Main PID: 20361 (centrifugo)
Tasks: 7 (limit: 4617)
Memory: 8.0M
CGroup: /system.slice/centrifugo.service
└─20361 /usr/bin/centrifugo --config /etc/centrifugo/config.json --admin
Jun 23 00:47:38 ubuntu systemd[1]: Starting Centrifugo Websocket Server…
Jun 23 00:47:38 ubuntu systemd[1]: Started Centrifugo Websocket Server.
Jun 23 00:47:38 ubuntu centrifugo[20361]: {"level":"info","version":"2.8.5","runtime":"go1.16.4","pid":20361,"engine":"Memory","gomaxprocs":2,"time":"2021-06-23T00:47:38-07:>
Jun 23 00:47:38 ubuntu centrifugo[20361]: {"level":"info","path":"/etc/centrifugo/config.json","time":"2021-06-23T00:47:38-07:00","message":"using config file"}
Jun 23 00:47:38 ubuntu centrifugo[20361]: {"level":"info","time":"2021-06-23T00:47:38-07:00","message":"serving websocket, SockJS, API, admin endpoints on :8000"}
~
By default, Centrifugo service listens to port 8000.
Run Centrifugo with Admin Panel
Now, you can log in to your web UI panel. This can be done by opening the following in your browser. Remember, you need the password from the configuration file as mentioned earlier in the guide.
http://IP-ADDRESS:8000
or
http://example.com:8000

After you log in, you will see the general information about the Centrifugo service in the UI.

Comments and Conclusion
In the guide, you learnt how to install and set up Centrifugo. The application itself is exceptional for working on every sort of back-end system where you may have several different systems in production environments. The software itself is well developed and for a free instant message chat.
Information on client set-up and integration can be found in the Centrifugo documentation.