How to move the office to real time IM on ejabberd

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 »

Move your office to ejabberd real time IM server

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


Let us know what you think 💬


18 thoughts on “How to move the office to real time IM on ejabberd

  1. Hi Marek,

    Great post!

    Can you confirm what are the extra ports you mentioned used for?

    3478 – ?
    5349 – ?
    5443 – ?

    Based on official ejabberd docs, i can see the following listed:

    5222 Standard port for Jabber/XMPP client connections, plain or STARTTLS.
    5223 Standard port for Jabber client connections using the old SSL method.
    5269 Standard port for Jabber/XMPP server connections.
    5280 Web GUI (http)

    Looking forward to your next post about setting up video calling. Thanks

    • Hi Frank,

      Thanks a lot! I’m working on the next post indeed, should be published soon. Regarding the ports:

      5443 – that’s encrypted Web GUI (https), it’s strongly advised to use that port over 5280 on webadmin panels that are exposed to the Internet.

      The other two ports are used with STUN/TURN discovery, which will be helpful with audio-video calling, but I’ll get into details in the next article. As such, these two ports are not necessary to complete this tutorial and I’ll possibly update the article to reflect that.

  2. How would one set up the host such that addresses are user@domain.name while the server itself is at the xmpp.domain.name subdomain? I’m assuming that the host would be domain.name with SRV records for _xmpp.client… and _xmpp.server… pointing to the xmpp.domain.name subdomain?

    Also, does ejabberd have to have access to the certificate file for the top-level domain or only the subdomains (xmpp, proxy, etc.)?

    • The best solution is to test such a setup, but I think the SRV records should be enough. ejabberd should only need the certificates for the endpoints. Please note that your web admin panel in such a setup will not be accessible from the main domain.

  3. Hello I’ve set up ejabberd with domain but i can’t access it through the domain, i can only access it through IP. How can I access ejabberd through domain?

    • You have to configure your domain to point to your server like you would with a website, and you have to open the appropriate ports on your server. Read your error logs etc.

      • I already configure my domain to point to my server as i can access it with mydomain:80. I can access ejabberd through IP like IP:5280/admin but when i try to access ejabberd through domain like mydomain:5280/admin it wont connect. I read the ejabberd log and there is no error in there. Is there any mistake from my ejabberd configuration?

  4. I have followed every step for setup tutorial and this one, I am able to communicate by text message but not able to make calling. Someone told me it is the TSL certificate issue. Because without a valid certificate calling can never be established over internet. My ejabberd is running on a VPS no web service. So I assume I have to apply for a certificate and place it in the server. Can you make a tutorial for this? Please make it as simple as the previous ones, those helped a lot. Thanks!

  5. 1.Can the admin only create users?
    Or 2. Can existing users of other xmpp clients join in
    3. Can anyone create a user?

    How to limit user creation

  6. Do you think you could write a tutorial to get ejabberd running behind a reverse proxy setup.
    Currently I have docker running an Nginx reverse proxy with a few services running behind it . I’m seriously interested in running a video call capable xmpp server with my setup, if it’s even possible. I’m sure it is but the amount of ports required to forward to internet , I’m not really sure where to start .

  7. Hi, Thank you for all. Everything works perfect for me.
    Could you please just add how to automate ssl cert renewal? Your instruction requires copying the renewed files manually to the /conf folder.
    Thank you in advance.
    Kind regards

    • Use letsencrypt certbot and add a bash script that copies the generated certs to the folder. This can be added in the deploy hooks folder of letsencrypt and will automatically be fired when the certbot runs

  8. Hi,

    I want to call our server API for sending push notifications from ejabberd when a stanza sends to offline users only in the MUC room.
    The main objective is that, sending push notifications to offline users when sending stanza in MUC.
    Is there any possibility of this? or can we integrate FCM or APNS for sending push for offline users?
    I have tried mod_push but it doesn’t work with FCM or APNS.
    Could you please provide any solution for this?

    Thanks.

  9. Hi
    Thanks for the tutorial.

    I configured ejabberd MUC with MYSQL.

    both db type and ram db type configured as sql. I am able to see data in muc_rooms, muc_online_rooms and muc_online_users table but muc_subscribers table is empty in mysql .

    When i use with clients like converse or siskin im group chat is working fine, user is able to rejoin after disconnect and connect again.

    Why muc_subscribers are empty? User joined the group through client.

Leave a Comment


This site uses Akismet to reduce spam. Learn how your comment data is processed.