ejabberd on AWS User Guide

Overview

This image runs ejabberd, a robust, massively scalable self-hosted XMPP (Jabber) real-time messaging server. It powers instant messaging, presence, multi-user chat rooms (MUC), publish-subscribe and push for your own users and applications, on your own infrastructure, speaking the open XMPP standard so any standards-compliant chat client can connect. It ships with ejabberd's built-in web administration console.

ejabberd is installed from the official ProcessOne binary package, which bundles its own Erlang/OTP runtime, and runs under a dedicated ejabberd service account managed by systemd. The web admin console is bound to the loopback interface on port 5280 and reached through nginx, which listens on port 80 and reverse-proxies to it with the WebSocket upgrade that XMPP-over-WebSocket and BOSH clients require. The client-to-server port 5222 and the server-to-server port 5269 are exposed directly. ejabberd's configuration, its Mnesia database of accounts, rosters and rooms, and its generated certificate live on a dedicated EBS data volume mounted at /var/lib/ejabberd, independently resizable and separate from the operating system disk.

On the first boot of every deployed instance, a one-shot service generates a fresh administrator account with a password unique to that instance, registers it as admin@localhost with server-administration rights, generates a fresh self-signed certificate, and records the credentials in /root/ejabberd-credentials.txt with mode 0600. No shared or default messaging account and no reused certificate ship in the image.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network, inbound port 80 (and 443 if you add HTTPS) from the networks your operators reach the web admin on, and inbound ports 5222 and 5269 from the networks your XMPP clients and federated servers connect from
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for ejabberd. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network, port 80 from your operators, and ports 5222 and 5269 from your clients and federated servers. Leave the root volume at the default size or larger; the image adds a separate data volume for the ejabberd database and certificate automatically.

Select Launch instance. First boot initialisation, which generates the certificate and the administrator account, takes about a minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg ejabberd Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, 5222 and 5269 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":20,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=ejabberd-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve the Administrator Credentials

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

The administrator credentials are written on first boot to a root-only file. Read them with:

sudo cat /root/ejabberd-credentials.txt

The file contains the web admin URL, the administrator Jabber ID (admin@localhost) and the password unique to this instance:

EJABBERD_WEB_ADMIN_URL=http://<public-ip>/admin/
EJABBERD_ADMIN_JID=admin@localhost
EJABBERD_PASSWORD=<generated-password>

You can confirm the server is running at any time with ejabberdctl:

sudo ejabberdctl status

The node ejabberd@localhost is started with status: started
ejabberd 26.4.0 is running in that node

Step 4: Sign In to the Web Admin Console

Open http://<public-ip>/admin/ in your browser. The web admin uses HTTP Basic authentication: enter the full Jabber ID admin@localhost as the user name and the generated password. The console opens on the ejabberd Web Admin home, from where you browse your XMPP virtual hosts, Erlang nodes and multi-user chat.

Select your virtual host (localhost) under Virtual Hosts to reach its administration page, with links to users, online users, announcements, multi-user chat, shared roster groups and statistics.

Step 5: Register Users

Open Users under your virtual host. Enter a user name and password under Register and choose Register to create an XMPP account, and see the registered accounts listed below.

You can also register users from the command line, which is convenient for scripting or bulk provisioning:

sudo ejabberdctl register alice localhost 'a-strong-password'
sudo ejabberdctl registered_users localhost

Step 6: Create Multi-User Chat Rooms

Open Multi-User Chat under your virtual host to reach the conference service (conference.localhost), where you create and administer group chat rooms.

To create a room from the command line:

sudo ejabberdctl create_room general conference.localhost localhost
sudo ejabberdctl muc_online_rooms global

Step 7: Connect an XMPP Client

Any standards-compliant XMPP client (for example Gajim, Conversations, Dino or Psi) can connect. Point the client at your server address, use a Jabber ID of the form user@localhost (or your real domain once you set one, see step 8), and the password you registered. Clients connect on:

• 5222 — client-to-server (c2s), for user logins
• 5269 — server-to-server (s2s), for federation with other XMPP servers

XMPP-over-WebSocket and BOSH are also served through nginx on port 80 at /ws and /bosh for web clients.

Step 8: Set a Real Domain and Certificate for Production

The appliance ships with the single XMPP virtual host localhost and a self-signed certificate so it works out of the box. For production, so that remote users and other servers can reach and trust your server, set your real XMPP domain and install a trusted certificate.

Edit the hosts list in the configuration file on the data volume:

sudo nano /var/lib/ejabberd/conf/ejabberd.yml   # set hosts: to <your-domain>

hosts:
  - chat.example.com

Point DNS at the instance (an A record for your domain, plus the XMPP SRV records _xmpp-client._tcp on 5222 and _xmpp-server._tcp on 5269), obtain a certificate for the domain (for example with Let's Encrypt), and set certfiles to it. Then reload the configuration and register your administrator on the new host:

sudo ejabberdctl reload_config
sudo ejabberdctl register admin <your-domain> '<a-strong-password>'

Add admin@chat.example.com to the admin ACL in ejabberd.yml so it can manage the new host, and reload again.

Health Endpoint

nginx serves an unauthenticated health endpoint for load-balancer and uptime checks:

curl http://<public-ip>/healthz

ok

Where Your Data Lives

ejabberd's configuration, its Mnesia database (accounts, rosters, multi-user chat rooms, PubSub nodes and offline messages) and its certificate live on a dedicated EBS data volume mounted at /var/lib/ejabberd. The binary installer's /opt/ejabberd path is a symlink onto this volume, so every stateful path resolves onto the dedicated disk:

findmnt -no SOURCE,TARGET,FSTYPE /var/lib/ejabberd

/dev/nvme1n1 /var/lib/ejabberd ext4

Because the data volume is separate from the operating system disk, you can snapshot it for backup and grow it independently. The server runs under systemd; check or control it with systemctl status ejabberd and manage the application with sudo ejabberdctl.

Maintenance

• Back up the data volume by taking an EBS snapshot, or export accounts and rooms with ejabberdctl commands.
• Restart the server with sudo systemctl restart ejabberd, and nginx with sudo systemctl restart nginx.
• Reload configuration after editing ejabberd.yml with sudo ejabberdctl reload_config (no restart needed for most changes).
• Upgrade the operating system with sudo apt-get update && sudo apt-get upgrade.

Support

cloudimg provides 24/7 technical support by email and chat. We can help with deployment, XMPP domain and certificate configuration, client and federation setup, chat-room and access-control design, clustering, storage and upgrade planning. Contact support through the channel listed on your AWS Marketplace subscription.