xmpp.chapril.org-ejabberd/CONTAINER.md

ejabberd Container

ejabberd is an open-source, robust, scalable and extensible realtime platform built using Erlang/OTP, that includes XMPP Server, MQTT Broker and SIP Service.

This document explains how to use the ejabberd container images available in the GitHub Container Registry, built using the files in .github/container/.

Alternatively, there are also ejabberd-ecs Docker images available in Docker Hub, built using the docker-ejabberd/ecs repository.

If you are using a Windows operating system, check the tutorials mentioned in ejabberd Docs > Docker Image.

Start ejabberd

With default configuration

Start ejabberd in a new container:

docker run --name ejabberd -d -p 5222:5222 ghcr.io/processone/ejabberd

That runs the container as a daemon, using ejabberd default configuration file and XMPP domain "localhost".

Stop the running container:

docker stop ejabberd

Restart the stopped ejabberd container:

docker restart ejabberd

Start with Erlang console attached

Start ejabberd with an Erlang console attached using the live command:

docker run --name ejabberd -it -p 5222:5222 ghcr.io/processone/ejabberd live

That uses the default configuration file and XMPP domain "localhost".

Start with your configuration and database

Pass a configuration file as a volume and share the local directory to store database:

mkdir database
chown ejabberd database

cp ejabberd.yml.example ejabberd.yml

docker run --name ejabberd -it \
  -v $(pwd)/ejabberd.yml:/opt/ejabberd/conf/ejabberd.yml \
  -v $(pwd)/database:/opt/ejabberd/database \
  -p 5222:5222 ghcr.io/processone/ejabberd live

Notice that ejabberd runs in the container with an account named ejabberd, and the volumes you mount must grant proper rights to that account.

Next steps

Register the administrator account

The default ejabberd configuration does not grant admin privileges to any account, you may want to register a new account in ejabberd and grant it admin rights.

Register an account using the ejabberdctl script:

docker exec -it ejabberd ejabberdctl register admin localhost passw0rd

Then edit conf/ejabberd.yml and add the ACL as explained in ejabberd Docs: Administration Account

Check ejabberd log files

Check the content of the log files inside the container, even if you do not put it on a shared persistent drive:

docker exec -it ejabberd tail -f logs/ejabberd.log

Inspect the container files

The container uses Alpine Linux. Start a shell inside the container:

docker exec -it ejabberd sh

Open ejabberd debug console

Open an interactive debug Erlang console attached to a running ejabberd in a running container:

docker exec -it ejabberd ejabberdctl debug

CAPTCHA

ejabberd includes two example CAPTCHA scripts. If you want to use any of them, first install some additional required libraries:

docker exec --user root ejabberd apk add imagemagick ghostscript-fonts bash

Now update your ejabberd configuration file, for example:

docker exec -it ejabberd vi conf/ejabberd.yml

and add the required options:

captcha_cmd: /opt/ejabberd-22.04/lib/ejabberd-22.04/priv/bin/captcha.sh
captcha_url: https://localhost:5443/captcha

Finally, reload the configuration file or restart the container:

docker exec ejabberd ejabberdctl reload_config

Advanced Container Configuration

Ports

This container image exposes the ports:

• 5222: The default port for XMPP clients.
• 5269: For XMPP federation. Only needed if you want to communicate with users on other servers.
• 5280: For admin interface.
• 5443: With encryption, used for admin interface, API, CAPTCHA, OAuth, Websockets and XMPP BOSH.
• 1883: Used for MQTT
• 4369-4399: EPMD and Erlang connectivity, used for ejabberdctl and clustering

Volumes

ejabberd produces two types of data: log files and database spool files (Mnesia). This is the kind of data you probably want to store on a persistent or local drive (at least the database).

The volumes you may want to map:

• /opt/ejabberd/conf/: Directory containing configuration and certificates
• /opt/ejabberd/database/: Directory containing Mnesia database. You should back up or export the content of the directory to persistent storage (host storage, local storage, any storage plugin)
• /opt/ejabberd/logs/: Directory containing log files
• /opt/ejabberd/upload/: Directory containing uploaded files. This should also be backed up.

All these files are owned by ejabberd user inside the container.

It's possible to install additional ejabberd modules using volumes, this comment explains how to install an additional module using docker-compose.

Commands on start

The ejabberdctl script reads the CTL_ON_CREATE environment variable the first time the docker container is started, and reads CTL_ON_START every time the container is started. Those variables can contain one ejabberdctl command, or several commands separated with the blankspace and ; characters.

Example usage (see full example docker-compose.yml):

    environment:
      - CTL_ON_CREATE=register admin localhost asd
      - CTL_ON_START=stats registeredusers ;
                     check_password admin localhost asd ;
                     status

Clustering

When setting several containers to form a cluster of ejabberd nodes, each one must have a different Erlang Node Name and the same Erlang Cookie.

For this you can either:

• edit conf/ejabberdctl.cfg and set variables ERLANG_NODE and ERLANG_COOKIE
• set the environment variables ERLANG_NODE_ARG and ERLANG_COOKIE

Example using environment variables (see full example docker-compose.yml):

    environment:
      - ERLANG_NODE_ARG=ejabberd@node7
      - ERLANG_COOKIE=dummycookie123

Generating a Container Image

This container image includes ejabberd as a standalone OTP release built using Elixir.

That OTP release is configured with:

• mix.exs: Customize ejabberd release
• vars.config: ejabberd compilation configuration options
• config/runtime.exs: Customize ejabberd paths
• ejabberd.yml.template: ejabberd default config file

Build ejabberd Community Server base image from ejabberd master on GitHub:

VERSION = master
docker build \
    --build-arg VERSION=$(VERSION) \
    -t personal/ejabberd:$(VERSION) \
    .github/container

Build ejabberd Community Server base image for a given ejabberd version, both for amd64 and arm64 architectures:

VERSION = 21.12
docker buildx build \
    --platform=linux/amd64,linux/arm64
    --build-arg VERSION=$(VERSION) \
    -t personal/ejabberd:$(VERSION) \
    .github/container

It's also possible to use podman instead of docker, just notice:

• EXPOSE 4369-4399 port range is not supported, remove that in Dockerfile
• It mentions that healthcheck is not supported by the Open Container Initiative image format
• If you want to start with command live, add environment variable EJABBERD_BYPASS_WARNINGS=true

VERSION = master
podman build \
    --build-arg VERSION=$(VERSION) \
    -t ja:$(version) \
    .github/container