How to move the office to real time IM on ejabberd

ProcessOne
· 6 min read
Send by email

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 weeks-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 an open source software, on hardware you control and can properly secure.

In this tutorial, I’ll describe how to setup an ejabberd real time IM platform. In my next tutorial, I’ll describe how to add video calling to ejabberd.

» Don’t want to configure IM yourself?
ProcessOne experts will make your business instantly connected. Contact us »

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 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.deb

apt install ./ejabberd_20.03.deb

Global configuration files are installed in /opt/ejabberd while the current version binaries are in /opt/ejabberd-20.03. Let’s look into the main configuration file:

nano /opt/ejabberd/conf/ejabberd.yml

By default, the hosts 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 marekfoss.org and change only the following parameters:

hosts
  - "marekfoss.org"
...
acl:
  ...
  admin:
    user:
      - "mf@marekfoss.org"
...
acme:
  contact: "mailto:mf@marekfoss.org"

Finally, I will start my ejabberd real time IM server:

/etc/init.d/ejabberd start

Then, let’s go through the necessary post-installation operations, like creating an admin user.

cd /opt/ejabberd-20.03/bin
./ejabberdctl register mf marekfoss.org ********
> User mf@marekfoss.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://marekfoss.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 fullchain.pem and privkey.pem to /opt/ejabberd/conf. Give ejabberd IM server file permissions by running chown ejabberd:ejabberd *.pem while in /opt/ejabberd/conf directory. Then update ejabberd.yml:

certfiles:
  - "/opt/ejabberd/conf/fullchain.pem"
  - "/opt/ejabberd/conf/privkey.pem"

After applying the changes by restarting ejabberd IM server with /etc/init.d/ejabberd restart, the web admin will be encrypted & available at https://marekfoss.org:5443/admin/. And I recommend to set 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.

Creating users in ejabberd real time IM server

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 labelling 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 into that field. That’s it. The next time your users reconnect, they will see contacts to their colleagues instantly.

Creating shared contact lists in ejabberd real time IM server

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.marekfoss.org marekfoss.org # creates a public chat room open@conference.marekfoss.org
./ejabberdctl change_room_option open conference.marekfoss.org persistent true # makes chat room persistent
./ejabberdctl change_room_option open conference.marekfoss.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.

» Do you need a more specific solution?
ProcessOne experts are ready to help. Contact us »

Set up video calling on your ejabberd real time IM platform

Your ejabberd real time IM platform is ready to use. Your office staff is instant messaging (IMing) one-to-one and in specified group chat rooms. Now, let’s move to the next step and set up voice & video calling on your ejabberd real time IM server.

In this ejabberd tutorial series:

Photo by Kevin Bhagat on Unsplash

Written by ProcessOne