Deploying ejabberd on Kubernetes: Tips and Example Configuration

Getting Started with ejabberd: A Beginner’s Guideejabberd is a robust, open-source XMPP (Extensible Messaging and Presence Protocol) server written in Erlang. It powers instant messaging, presence, group chat, and many real-time communication features for projects ranging from small hobby deployments to large-scale commercial services. This guide walks you through the essentials: what ejabberd is, how it works, installation options, basic configuration, user and roster management, security and scaling basics, and pointers for further learning.

What is ejabberd and why choose it?

ejabberd implements the XMPP protocol, a widely adopted open standard for exchanging structured information in near real-time. Key strengths of ejabberd:

Scalability: Built in Erlang, designed for highly concurrent, fault-tolerant systems.
Extensibility: Modular architecture with many built-in XMPP extensions (XEPs) and support for custom modules.
Clustering: Native clustering support to distribute load across multiple nodes.
Mature ecosystem: Long history, active community, and commercial support available from ProcessOne.
Protocol compliance: Implements core XMPP features and many useful XEPs (Multi-User Chat, PubSub, vCard, Message Archive Management, etc.).

Basic XMPP concepts you should know

Jabber ID (JID): user@domain/resource — identity in XMPP.
Presence: online/offline/away status and availability information.
Roster: a user’s contact list containing subscribed JIDs.
Stanza: an XML fragment (message, presence, IQ) used for XMPP communication.
MUC (Multi-User Chat): group chat rooms implemented by XEP-0045.
PubSub: publish–subscribe pattern for event distribution (XEP-0060).

Installation

There are multiple ways to install ejabberd depending on your environment and needs: binary installer, package manager, Docker, and from source. Below are concise steps for common options.

Option A — Official binary installer (recommended for production evaluation)

Download the latest installer for your OS from the ejabberd website.
Run the installer (Linux: run the .run file as root; macOS: .pkg; Windows: .exe).
The installer sets up an ejabberd service and places configuration files in /etc/ejabberd/ or the chosen install dir.

Option B — Package manager (Debian/Ubuntu example)

On Debian/Ubuntu:

sudo apt update sudo apt install ejabberd

Configuration files typically live in /etc/ejabberd/ejabberd.yml.

Option C — Docker (good for testing and containerized deployments)

Official Docker image:

docker run -d --name ejabberd -p 5222:5222 -p 5280:5280 ejabberd/ecs

Mount a local config directory and persistent volumes for Mnesia/DB as needed.

Option D — From source (advanced, for development)

Install Erlang/OTP (compatible version).
Download ejabberd source from the Git repository or release tarball.
Follow README instructions: compile with rebar or Makefile and install.

First-time configuration (ejabberd.yml basics)

ejabberd’s primary configuration file is ejabberd.yml. Key areas to edit:

Hosts: define domains the server will serve. Example: “` hosts:
- “example.com” “`
Admins: list JIDs with administrative privileges. Example:
```
acl: admin:   user:     - "admin": "example.com" 
```
Listening ports: configure c2s/s2s/http components (5222, 5269, 5280).
Modules: enable/disable and configure modules like mod_muc, mod_offline, mod_pubsub, mod_vcard.
Authentication: internal (database), LDAP, external script, or OAuth integrations.

After editing, restart ejabberd:

sudo systemctl restart ejabberd

or if running in Docker, restart the container.

Creating users and basic admin tasks


ejabberdctl register alice example.com password123

List registered users:


ejabberdctl registered_users example.com

Change a user’s password:


ejabberdctl change_password alice example.com newpass

Grant admin rights (if not set in config):


ejabberdctl set_admin "[email protected]"

For small setups you can also enable in-band registration (mod_register) to allow users to sign up from clients; for production, prefer controlled registration or invite flows.

Connecting a client

Use any XMPP client (e.g., Conversations on Android, Dino on desktop, Gajim). Client settings:

Username/JID: [email protected]
Password: the password you registered
Server/Host: example.com (or IP if DNS not set)
Port: 5222 (default)
Resource: optional (client-specific instance)
Use TLS/SSL: Yes (STARTTLS on 5222)

If you’ve enabled the web admin module (mod_http_api, ejabberd_web_admin), point your browser at https://example.com:5280/admin to manage users and view logs.

Security essentials

Use TLS for client-to-server and server-to-server connections. Configure certificates (Let’s Encrypt or commercial CAs) and disable plaintext auth.
Disable in-band registration for production or protect it with CAPTCHA/external approval.
Regularly update ejabberd and Erlang to receive security fixes.
Use strong passwords and consider external authentication (LDAP, OAuth) for centralized identity.
Limit and monitor s2s (server-to-server) connections if you only want trusted federated domains.

Storage and message history

ejabberd supports different backends:

Mnesia (default Erlang DB): simple and fast for many use cases; replicates across cluster nodes.
SQL databases (PostgreSQL/MySQL): use for larger persistent storage, archiving, and analytics. Configure in ejabberd.yml under sql_type and database settings.
Message Archive Management (XEP-0313): store/retrieve message history; supported via modules like mod_mam and mod_mam_sql.

Clustering and scaling

Clustering is a major strength. Basic points:

Erlang distribution connects ejabberd nodes; Mnesia replicates state.
Use a load balancer (TCP-aware) or route clients to specific nodes; web sockets and BOSH require sticky sessions or reverse proxy support.
Offload file storage and heavy processing (push notifications, media storage) to external services.
Monitor metrics (process counts, queues, CPU, memory). Integrations for Prometheus and Grafana are common.

Useful modules and extensions

mod_muc — Multi-User Chat (group rooms)
mod_offline — store offline messages
mod_vcard — user profiles
mod_pubsub — publish-subscribe services
mod_mam — message archive management (history)
mod_http_api / ejabberd_web_admin — admin HTTP API and web interface
mod_rest — REST API for external integrations
mod_push — push notifications

Example: enable MUC and web admin (snippet)

In ejabberd.yml, ensure modules include:

modules:   mod_muc: {}   ejabberd_web_admin: {}   mod_http_api: {}

Configure listener for HTTP on 5280 and TLS for secure admin access.

Troubleshooting common issues

Clients can’t connect: check listening ports, firewall rules, TLS certificate validity, and DNS SRV records (_xmpp-client._tcp.example.com).
Federation problems (s2s): verify port 5269 open, DNS for domain, and valid certificates.
User authentication failures: confirm auth method matches configuration (internal vs external) and check logs (/var/log/ejabberd/ or configured log dir).
High memory/CPU: inspect number of connected clients, enable monitoring, and consider clustering.

Next steps and resources

Read ejabberd documentation for module-specific options and advanced configuration.
Experiment locally with Docker to learn client connections, MUC, and MAM.
Explore client libraries (xmpp.js, stanza.io, Smack for Java) to build custom clients and bots.
Monitor and log with Prometheus/Grafana for production insight.

If you want, I can: provide a ready-to-use ejabberd.yml starter file for example.com, show Docker compose for an ejabberd + PostgreSQL setup, or walk through configuring TLS with Let’s Encrypt.