Skip to content

Install ejabberd from Source Code

The canonical distribution form of ejabberd stable releases is the source code package. Compiling ejabberd from source code is quite easy in *nix systems, as long as your system have all the dependencies.

Requirements

To compile ejabberd you need:

  • GNU Make
  • GCC
  • Libexpat ≥ 1.95
  • Libyaml ≥ 0.1.4
  • Erlang/OTP ≥ 20.0. We recommend using Erlang OTP 26.2, which is the version used in the binary installers and container images.
  • OpenSSL ≥ 1.0.0

Other optional libraries are:

If your system splits packages in libraries and development headers, install the development packages too.

For example, in Debian:

apt-get install libexpat1-dev libgd-dev libpam0g-dev \
                libsqlite3-dev libwebp-dev libyaml-dev \
                autoconf automake erlang elixir rebar3

Download

There are several ways to obtain the ejabberd source code:

Compile

The generic instructions to compile ejabberd are:

./autogen.sh
./configure
make

Let's view them in detail.

./configure

The build configuration script supports many options. Get the full list:

./configure --help

In this example, ./configure prepares the installed program to run with a user called ejabberd that should exist in the system (it isn't recommended to run ejabberd with root user):

./configure --enable-user=ejabberd --enable-mysql

If you get Error loading module rebar3, please consult how to use rebar with old Erlang.

Options details:

  • --bindir=/: Specify the path to the user executables (where epmd and iex are available).

  • --prefix=/: Specify the path prefix where the files will be copied when running the make install command.

  • --with-rebar=/: Specify the path to rebar, rebar3 or mix

    added in 20.12 and improved in 24.02

  • --enable-user[=USER]: Allow this normal system user to execute the ejabberdctl script (see section ejabberdctl), read the configuration files, read and write in the spool directory, read and write in the log directory. The account user and group must exist in the machine before running make install. This account needs a HOME directory, because the Erlang cookie file will be created and read there.

  • --enable-group[=GROUP]: Use this option additionally to --enable-user when that account is in a group that doesn't coincide with its username.

  • --enable-all: Enable many of the database and dependencies options described here, this is useful for Dialyzer checks: --enable-debug --enable-elixir --enable-mysql --enable-odbc --enable-pam --enable-pgsql --enable-redis --enable-sip --enable-sqlite --enable-stun --enable-tools --enable-zlib

  • --disable-debug: Compile without +debug_info.

  • --enable-elixir: Build ejabberd with Elixir extension support. Works only with rebar3, not rebar2. Requires to have Elixir installed. If interested in Elixir development, you may prefer to use --with-rebar=mix

    improved in 24.02

  • --disable-erlang-version-check: Don't check Erlang/OTP version.

  • --enable-full-xml: Use XML features in XMPP stream (ex: CDATA). This requires XML compliant clients).

  • --enable-hipe: Compile natively with HiPE. This is an experimental feature, and not recommended.

  • --enable-lager: Use lager Erlang logging tool instead of standard error logger.

  • --enable-latest-deps: Makes rebar use latest versions of dependencies developed alongside ejabberd instead of version specified in rebar.config. Should be only used when developing ejabberd.

  • --enable-lua: Enable Lua support, to import from Prosody.

    added in 21.04

  • --enable-mssql: Enable Microsoft SQL Server support, this option requires --enable-odbc (see [Supported storages][18]).

  • --enable-mysql: Enable MySQL support (see [Supported storages][18]).

  • --enable-new-sql-schema: Use new SQL schema.

  • --enable-odbc: Enable pure ODBC support.

  • --enable-pam: Enable the PAM authentication method (see PAM Authentication section).

  • --enable-pgsql: Enable PostgreSQL support (see [Supported storages][18]).

  • --enable-redis: Enable Redis support to use for external session storage.

  • --enable-roster-gateway-workaround: Turn on workaround for processing gateway subscriptions.

  • --enable-sip: Enable SIP support.

  • --enable-sqlite: Enable SQLite support (see [Supported storages][18]).

  • --disable-stun: Disable STUN/TURN support.

  • --enable-system-deps: Makes rebar use locally installed dependencies instead of downloading them.

  • --enable-tools: Enable the use of development tools.

    changed in 21.04

  • --disable-zlib: Disable Stream Compression (XEP-0138) using zlib.

make

This gets the erlang depencies and compiles everything, among other tasks:

Get the full task list:

make help

Note: The required erlang dependencies are downloaded from Internet. Or you can copy $HOME/.hex/ package cache from another machine.

Install

There are several ways to install and run ejabberd after it's compiled from source code:

System Install

To install ejabberd in the destination directories, run:

make install

Note that you probably need administrative privileges in the system to install ejabberd.

The created files and directories depend on the options provided to ./configure, by default they are:

  • /etc/ejabberd/: Configuration directory:

    • ejabberd.yml: ejabberd configuration file (see File Format)
    • ejabberdctl.cfg: Configuration file of the administration script (see Erlang Runtime System)
    • inetrc: Network DNS configuration file for Erlang

  • /lib/ejabberd/:

    • ebin/: Erlang binary files (*.beam)
    • include/: Erlang header files (*.hrl)
    • priv/: Additional files required at runtime
    • bin/: Executable programs
    • lib/: Binary system libraries (*.so)
    • msgs/: Translation files (*.msgs) (see Default Language)

  • /sbin/ejabberdctl: Administration script (see ejabberdctl)

  • /share/doc/ejabberd/: Documentation of ejabberd

  • /var/lib/ejabberd/: Spool directory:

    • .erlang.cookie: The Erlang cookie file
    • acl.DCD, ...: Mnesia database spool files (*.DCD, *.DCL, *.DAT)

  • /var/log/ejabberd/: Log directory (see Logging):

    • ejabberd.log: ejabberd service log
    • erlang.log: Erlang/OTP system log

System Install Release

added in 24.02

This builds a production release, and then performs a system install of that release, obtaining a result similar to the one mentioned in the previous section.

Simply run:

make install-rel

The benefits of install-rel over install:

  • this uses OTP release code from rebar/rebar3/mix, and consequently requires less code in our Makefile.in file
  • uninstall-rel correctly deletes all the library files
  • the *.beam files are smaller as debug information is stripped

Production Release

improved in 21.07

You can build an OTP release that includes ejabberd, Erlang/OTP and all the required erlang dependencies in a single tar.gz file. Then you can copy that file to another machine that has the same machine architecture, and run ejabberd without installing anything else.

To build that production release, run:

make prod

If you provided to ./configure the option --with-rebar to use rebar3 or mix, this will directly produce a tar.gz that you can copy.

This example uses rebar3 to manage the compilation, builds an OTP production release, copies the resulting package to a temporary path, and starts ejabberd there:

./autogen.sh
./configure --with-rebar=rebar3
make
make prod
mkdir $HOME/eja-release
tar -xzvf _build/prod/ejabberd-*.tar.gz -C $HOME/eja-release
$HOME/eja-release/bin/ejabberdctl live

Development Release

new in 21.07

If you provided to ./configure the option --with-rebar to use rebar3 or mix, you can build an OTP development release.

This is designed to run ejabberd in the local machine for development, manual testing... without installing in the system.

This development release has some customizations: uses a dummy certificate file, if you register the account admin@localhost it has admin rights...

This example uses Elixir's mix to manage the compilation, builds an OTP development release, and starts ejabberd there:

./autogen.sh
./configure --with-rebar=mix
make
make dev
_build/dev/rel/ejabberd/bin/ejabberdctl live

Specific notes

asdf

When Erlang/OTP (and/or Elixir) is installed using asdf (multiple runtime version manager), it is available only for your account, in $HOME/.asdf/shims/erl. In that case, you cannot install ejabberd globally in the system, and you cannot use the root account to start it, because that account doesn't have access to erlang.

In that scenario, there are several ways to run/install ejabberd:

./autogen.sh
./configure --prefix=$HOME/eja-install --enable-user
make
make install
$HOME/eja-install/sbin/ejabberdctl live

BSD

The command to compile ejabberd in BSD systems is gmake.

You may want to check pkgsrc.se for ejabberd.

Up to ejabberd 23.04, some old scripts where included in ejabberd source for NetBSD compilation, and you can take a look to those files for reference in ejabberd 23.04/examples/mtr/ path.

macOS

If compiling from sources on Mac OS X, you must configure ejabberd to use custom OpenSSL, Yaml, iconv. The best approach is to use Homebrew to install your dependencies, then exports your custom path to let configure and make be aware of them.

brew install git erlang elixir openssl expat libyaml libiconv libgd sqlite rebar rebar3 automake autoconf
export LDFLAGS="-L/usr/local/opt/openssl/lib -L/usr/local/lib -L/usr/local/opt/expat/lib"
export CFLAGS="-I/usr/local/opt/openssl/include -I/usr/local/include -I/usr/local/opt/expat/include"
export CPPFLAGS="-I/usr/local/opt/openssl/include/ -I/usr/local/include -I/usr/local/opt/expat/include"
./configure
make

Check also the guide for Installing ejabberd development environment on OSX

man

ejabberd includes a man page which documents the toplevel and modules options, the same information that is published in the Top-Level Options and Modules Options sections.

The man file can be read locally with:

man -l man/ejabberd.yml.5

rebar with old Erlang

The ejabberd source code package includes rebar and rebar3 binaries that work with Erlang/OTP 24.0 up to 27.

To compile ejabberd using rebar/rebar3 and Erlang 20.0 up to 23.3, you can install it from your operating system, or compile yourself from the rebar source code, or download the old binary from ejabberd 21.12:

wget https://github.com/processone/ejabberd/raw/21.12/rebar
wget https://github.com/processone/ejabberd/raw/21.12/rebar3

Start

You can use the ejabberdctl command line administration script to start and stop ejabberd. Some examples, depending on your installation method:

  • When installed in the system: 

    ejabberdctl start
/sbin/ejabberdctl start

  • When built an OTP production release: 

    _build/prod/rel/ejabberd/bin/ejabberdctl start
_build/prod/rel/ejabberd/bin/ejabberdctl live

  • Start interactively without installing or building OTP release: 

    make relive