docs.ejabberd.im

Installing ejabberd


There are several ways to install ejabberd Community Server:

Once installed, you can head to the next steps:

Linux RUN Installer

The *.run binary installer will deploy and configure a full featured ejabberd server and does not require any extra dependencies. It includes a stripped down version of Erlang. As such, when using ejabberd installer, you do not need to install Erlang separately.

Those instructions assume installation on localhost for development purposes. In this document, when mentioning ejabberd-YY.MM, we assume YY.MM is the release number, for example 18.01.

Installation using the *.run binary installer:

  1. Go to ejabberd GitHub Releases.

  2. Download the run package for your architecture

  3. Right-click on the downloaded file and select "Properties", click on the "Permissions" tab and tick the box that says "Allow executing file as program". Alternatively, you can set the installer as executable using the command line:

    chmod +x ejabberd-YY.MM-1-linux-x64.run
    
  4. If the installer runs as superuser (by root or using sudo), it installs ejabberd binaries in /opt/ejabberd-XX.YY/; installs your configuration, Mnesia database and logs in /opt/ejabberd/, and setups an ejabberd service unit in systemd:

    sudo ./ejabberd-YY.MM-1-linux-x64.run
    
  5. If the installer runs as a regular user, it asks the base path where ejabberd should be installed. In that case, the ejabberd service unit is not set in systemd, and systemctl cannot be used to start ejabberd; start it manually.

  6. After successful installation by root, ejabberd is automatically started. Check its status with

    systemctl status ejabberd
    
  7. Now that ejabberd is installed and running with the default configuration, it's time to do some basic setup: edit /opt/ejabberd/conf/ejabberd.yml and setup in the hosts option the domain that you want ejabberd to serve. By default it's set to the name of your computer on the local network.

  8. Restart ejabberd completely using systemctl, or using ejabberdctl, or simply tell it to reload the configuration file:

    sudo systemctl restart ejabberd
    sudo /opt/ejabberd-22.05/bin/ejabberdctl restart
    sudo /opt/ejabberd-22.05/bin/ejabberdctl reload_config
    
  9. Quite probably you will want to register an account and grant it admin rights, please check Administration Account.

  10. Now you can go to the web dashboard at http://localhost:5280/admin/ and fill the username field with the full account JID, for example admin@domain (or admin@localhost as above). Then fill the password field with that account's password. The next step is to get to know how to configure ejabberd.

  11. If something goes wrong during the installation and you would like to start from scratch, you will find the steps to uninstall in the file /opt/ejabberd-22.05/uninstall.txt.

Linux DEB and RPM Installers

ProcessOne provides DEB and RPM all-in-one binary installers with the same content that the *.run binary installer mentioned in the previous section.

Those are self-sufficient packages that contain a minimal Erlang distribution, this ensures that it does not interfere with your existing Erlang version and is also a good way to make sure ejabberd will run with the latest Erlang version.

Those packages install ejabberd in /opt/ejabberd-XX.YY/. Your configuration, Mnesia database and logs are available in /opt/ejabberd/.

You can download directly the DEB and RPM packages from ejabberd GitHub Releases.

If you prefer, you can also get those packages from our official ejabberd packages repository.

Operating System Packages

Many operating systems provide specific ejabberd packages adapted to the system architecture and libraries. They usually also check dependencies and perform basic configuration tasks like creating the initial administrator account.

List of known ejabberd packages:

Consult the resources provided by your Operating System for more information.

There's also an ejabberd snap to install ejabberd on several operating systems using Snap package manager.

Docker Image

The "ecs" container image allows to get ejabberd stable releases in x64 machines. Check the "ecs" container documentation. Download ejabberd with:

docker pull docker.io/ejabberd/ecs

There is an alternative "ejabberd" container image available in the GitHub Container Registry. This one is available for x64 and arm64, both for stable ejabberd releases and the master branch. Check the "ejabberd" container documentation. For example, download the latest stable ejabberd release:

docker pull ghcr.io/processone/ejabberd

If you use Microsoft Windows 7, 10, or similar operating systems, check those tutorials:

For bug reports and improvement suggestions, if you use the "ecs" container image please go to the docker-ejabberd GitHub Issues, if using the "ejabberd" container image from github please go to the ejabberd GitHub Issues

Homebrew

Homebrew is a package manager for macOS that aims to port the many Unix & Linux software that is not easily available or compatible. Homebrew installation is simple and the instruction is available on its website.

Check also the guide for Installing ejabberd development environment on OSX

The ejabberd configuration included in Homebrew's ejabberd has as default domain localhost, and has already granted administrative privileges to the account admin@localhost.

  1. Once you have Homebrew installed, open Terminal. Run

    brew install ejabberd
    

    This should install the latest or at most the one-before-latest version of ejabberd. The installation directory should be reported at the end of this process, but usually the main executable is stored at /usr/local/sbin/ejabberdctl.

  2. Start ejabberd in interactive mode, which prints useful messages in the Terminal.

    /usr/local/sbin/ejabberdctl live
    
  3. Create the account admin@localhost with password set as password:

    /usr/local/sbin/ejabberdctl register admin localhost password
    
  4. Now you can go to the web dashboard at http://localhost:5280/admin/ and fill the username field with the full account JID, for example admin@localhost, then fill the password field with that account's password.

  5. Without configuration there's not much to see here, therefore the next step is to get to know how to configure ejabberd.

Source Code

The canonical form for distribution 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 on a ‘Unix-like’ operating system, you need:

  • GNU Make
  • GCC
  • Libexpat 1.95 or higher
  • Libyaml 0.1.4 or higher
  • Erlang/OTP 20.0 or higher. Erlang OTP 26.2 is suggested, in fact that's the version used in the binary installers and container images.
  • OpenSSL 1.0.0 or higher, for STARTTLS, SASL and SSL encryption.
  • Zlib 1.2.3 or higher. Optional. For Zlib Stream Compression
  • PAM library. Optional. For PAM Authentication
  • ImageMagick’s Convert program and Ghostscript fonts. Optional. For CAPTCHA challenges.
  • Elixir 1.10.3 or higher. It is recommended Elixir 1.13.4 or higher and Erlang/OTP 23.0 or higher. Optional. For Elixir Development

Downloading

Released versions of ejabberd are available for download from ejabberd GitHub Releases.

Alternatively, the latest development source code can be retrieved from the Git repository using the commands:

git clone git://github.com/processone/ejabberd.git ejabberd
cd ejabberd

Compilation

To compile ejabberd execute the commands:

./autogen.sh
./configure --enable-user=ejabberd --enable-mysql
make

In this example, ./configure prepares the installed program to run with a user called ejabberd, so please create that user or tell to use another local user. It isn't recommended to run ejabberd with root user.

make gets the dependencies and compiles everything.

Note: To build ejabberd, you will need Internet access, as dependencies will be downloaded depending on the selected options.

./configure

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

./configure --help

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.

added in 20.12 and improved in 24.02


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

  • --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.

improved in 24.02


  • --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

  • --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.

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

  • --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.

changed in 21.04
  • --enable-tools: Enable the use of development tools.

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

make

This tool is used to compile ejabberd and perform other tasks:

Get the full list and details:

make help

Installation

There are several ways to install and run the ejabberd compiled from source code: system install, building a production release, or building a development release.

System Install

To install ejabberd in the destination directories, run the command 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

improved in 21.07

Production Release

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

new in 21.07

Development Release

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:

  • Run a development release locally without installing

  • Copy a production release locally

  • Use system install, but install it locally:

    ./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

Next Steps

Starting ejabberd

Depending on how you installed ejabberd, it may be started automatically by the operating system at system boot time.

You can use the ejabberdctl command line administration script to start and stop ejabberd, check its status and many other administrative tasks.

If you provided the configure option --enable-user=USER (see compilation options), you can execute ejabberdctl with either that system account or root.

Usage example:

prompt> ejabberdctl start

prompt> ejabberdctl status
The node ejabberd@localhost is started with status: started
ejabberd is running in that node

prompt> ejabberdctl stop

If ejabberd doesn't start correctly and a crash dump file is generated, there was a severe problem. You can try to start ejabberd in interactive mode with the command bin/ejabberdctl live to see the error messages provided by Erlang and identify the exact the problem.

The ejabberdctl administration script is included in the bin directory in the Linux Installers and Docker image.

Please refer to the section ejabberdctl for details about ejabberdctl, and configurable options to fine tune the Erlang runtime system.

Autostart on Linux

If you compiled ejabberd from source code or some other method that doesn't setup autostarting ejabberd, you can try this method.

On a *nix system, create a system user called 'ejabberd', give it write access to the directories database/ and logs/, and set that as home.

If you want ejabberd to be started as daemon at boot time with that user, copy ejabberd.init from the bin directory to something like /etc/init.d/ejabberd. Then you can call /etc/inid.d/ejabberd start to start the server.

Or if you have a systemd distribution:

  1. copy ejabberd.service to /etc/systemd/system/
  2. run systemctl daemon-reload
  3. run systemctl enable ejabberd.service
  4. To start the server, you can run systemctl start ejabberd

When ejabberd is started, the processes that are started in the system are beam or beam.smp, and also epmd. For more information regarding epmd consult the section relating to epmd.

Administration Account

Some ejabberd installation methods ask you details for the first account, and take care to register that account and grant it administrative rights; in that case you can skip this section.

After installing ejabberd from source code or other methods, you may want to register the first XMPP account and grant it administrative rights:

  1. Register an XMPP account on your ejabberd server. For example, if example.org is configured in the hosts section in your ejabberd configuration file, then you may want to register an account with JID admin1@example.org. There are two ways to register an XMPP account in ejabberd:

  2. Edit the ejabberd configuration file to give administration rights to the XMPP account you registered:

    acl:
      admin:
        user: admin1@example.org
    
    access_rules:
      configure:
        allow: admin
    

    You can grant administrative privileges to many XMPP accounts, and also to accounts in other XMPP servers.

  3. Restart ejabberd to load the new configuration, or run the reload_config command.

  4. Open the Web Admin page in your favourite browser. The exact address depends on your ejabberd configuration, and may be http://localhost:5280/admin/, https://localhost:5443/admin/, https://localhost:5280/admin/ ...

  5. Your web browser shows a login window. Introduce the full JID, in this example admin1@example.org, and the account password. If the web address hostname is the same that the account JID, you can provide simply the username instead of the full JID: admin1. See Web Admin for details.

Configuring ejabberd

Now that you got ejabberd installed and running, it's time to configure it to your needs. You can follow on the Configuration section and take also a look at the Tutorials.