Move your workplace to real-time IM on ejabberd — a quick overview.
During a pandemic, businesses around the world face the same fundamental problem: how to quickly move office staff to work remotely from home? You need an instant messaging (IM) platform like the ejabberd real-time IM server. Of course, you can choose other cloud services, but they come with a common set of problems:
- Your business becomes very dependent on an external service. Any downtime means your office goes silent (ekhm, MS Teams).
- Your business inherits all the vulnerabilities of the external service. Your office staff is open to hacking (ekhm, Zoom…).
- Your business costs aren’t scalable. External services charge by the seat, so your bill becomes significant overnight and grows when your office grows.
Deploying your own IM solution may sound like a week-long project for your IT department. But in fact, with ejabberd real-time IM server, it’s quick and free. And you will be using open-source software, on hardware, you control and can properly secure.
In this tutorial, I’ll describe how to set up an ejabberd real time IM platform.
Install ejabberd real-time IM server
You can set up your ejabberd real-time IM platform on a VPS server. Or on a server inside your company VPN. You can even install it on a laptop. Just make sure it’s connected to the Web using a static IP. And your Internet router forwards the necessary ports, so the laptop is reachable from the outside world.
You can install an ejabberd real-time IM server on any Linux, Windows or macOS machine. Follow this guide and install ejabberd on a system of your choice »
For the purpose of this tutorial, I will be installing ejabberd 20.03 on a small VPS running Debian Linux. I start with downloading the correct ejabberd real-time IM server installer to my home directory and installing it:
wget https://www.process-one.net/downloads/downloads-action.php?file=/20.03/ejabberd_20.03-0_amd64.deb -O ejabberd_20.03.debapt install ./ejabberd_20.03.deb
Global configuration files are installed
/opt/ejabberd while the current version binaries are in
/opt/ejabberd-20.03. Let’s look into the main configuration file:
By default, the
hosts the parameter will contain the internal name of your VPS. But we would like to use a real-world domain here. In this example, I will be using the domain
your_company.org and change only the following parameters:
Finally, I will start my ejabberd real-time IM server:
Then, let’s go through the necessary post-installation operations, like creating an admin user.
./ejabberdctl register admin your_company.org ********
> User admin@your_company.org successfully registered
We need to allow traffic on several ports for ejabberd real-time IM server to work properly: 5222, 5269, 5443, and 5280. The last port opens an unencrypted web admin console for us at
http://your_company.org:5280/admin/ to which we log in using the admin user we just created.
However, if you happen to install ejabberd real-time IM server on a VPS that already hosts a website with your domain, and you already use Let’s Encrypt SSL certificates, simply copy the
/opt/ejabberd/conf. Give ejabberd IM server file permissions by running
chown ejabberd:ejabberd *.pem while in the
/opt/ejabberd/conf directory. Then update
After applying the changes by restarting ejabberd IM server,
/etc/init.d/ejabberd restart the web admin will be encrypted & available at
https://your_company.org:5443/admin/. And I recommend setting your VPS firewall to limit access to that page to your local static IP and block the unencrypted access via port 5280 altogether. However, not all firewalls allow filtering by port and request directory. If you block access to port 5443 in general, many extra features, like File Uploads or XMPP WebSockets, won’t work outside your IP.
Create chat users in ejabberd real-time IM server
In the web admin console, using the side menu, go to Virtual Hosts and click on your domain. Then from the side menu select Users. You can add each user by typing in the username and password. All users appear on the list below.
Create shared contact lists in ejabberd real-time IM server
Once all users have their accounts, it would be nice if just after logging into their favorite XMPP client (I’ll suggest some apps later on) they could see all their colleagues in the contact list. For this, we need to create a shared contact list (shared roster).
Simply go to Shared Roster Groups, type a new group name, for example,
Default and click Add New. Then, click on the Default group that appears above to see its settings.
In the settings, the Name field defines how this group will be called in people’s XMPP clients. For example, you could type
Everyone here. But for admin purposes, your group is still called Default, as you set when creating it. It’s a crucial distinction because for this group to be loaded automatically by people’s XMPP clients, you must type its admin name (Default) in the Displayed Groups field. EDIT: the labeling on this element was updated in ejabberd 20.04 to reduce confusion.
And in Members type
@all@. It’s a special variable that automatically adds all users to that field. That’s it. The next time your users reconnect, they will see contacts with their colleagues instantly.
Create rooms for IM group chats
Now that all your users can chat with each other, it’s time to create chat rooms (also known as group chats or Multi-User Chats). It’s quite simple, really. You do it right in your XMPP client. Most of them have it under the plus sign, where you can choose to start a new chat with a specific person, join a chat room, or create one.
However, chat rooms created this way will not be persistent and will vanish once the last person leaves (in default ejabberd configuration). I suggest not giving non-admin users the power to create many persistent rooms. Instead, it’s better to create persistent chat rooms directly from the VPS server terminal. This way, your office real-time IM server will be more organized.
cd /opt/ejabberd-20.03/bin ./ejabberdctl create_room open conference.your_company.org your_company.org # creates a public chat room email@example.com_company.org
./ejabberdctl change_room_option open conference.your_company.org persistent true # makes chat room persistent./ejabberdctl change_room_option open conference.your_company.org title "Open Discussion" # assigns a room title
Once an IM chat room is created this way, it remains available even without participants, unless you explicitly delete it. It keeps its chat history etc. It will also be visible on the list in your web admin console under Multi-User Chat.
Install IM chat apps (XMPP clients)
There are many different IM chat apps (XMPP clients), for many different platforms: macOS, Windows, Linux, iOS, Android… You can find a complete list here.
You don’t even have to install anything. There’s a very good IM chat client called Converse that works right in your browser and connects directly to your server. It will be great on desktops, laptops, and tablets.
For Android smartphones, I can recommend Conversations, a fully-featured real-time IM client. Although it’s a paid app on Google Play Store, if you are familiar with F-Droid you can install it for free.
For iPhones and iPads, one interesting option is ChatSecure.