Join 10350+ others. No spamming.
I promise!

Follow us at github.



esl / MongooseIM


MongooseIM is a mobile messaging platform with focus on performance and scalability


MongooseIM Build Status Documentation Status Coverage Status

MongooseIM is Erlang Solutions' robust and efficient XMPP server aimed at large installations. Specifically designed for enterprise purposes, it is fault-tolerant, can utilize resources of multiple clustered machines and easily scale in need of more capacity (by just adding a box/VM).

MongooseIM can accept client sessions over vanilla XMPP, Websockets, and HTTP long-polling (a.k.a. BOSH).

Its home on GitHub is at

Download packages

For a quick start just download the pre-built package that suits your platform: Ubuntu, Debian, CentOS, and Mac OS X.

An experimental Docker image exists on: You can contribute on:

Main differences from the parent project

This project began its life as a fork of ejabberd v.2.1.8 and later underwent some major cleanup, refactorization and optimization.

Major steps performed:

  • bringing the project source tree to compliance with OTP project structure recommendations,
  • swapping autotools for the Erlang community-standard build tool rebar,
  • removal of obsolete and/or rarely used modules to reduce maintenance burden,
  • reduction of runtime memory consumption by refactoring the code to use Erlang's binary data type for string manipulation and storage instead of operating on linked lists of characters,
  • functional test coverage of the system according to corresponding RFCs and XEPs.


Up-to-date documentation for the MongooseIM master branch can be found on ReadTheDocs:

When developing new features/modules, please take care to add basic documentation to the doc/ directory, and add a link to your document in doc/

Original documentation for Ejabberd-2.1.8, from which MongooseIM was forked, is preserved in doc/ejabberd-2.1.8-OLD.

Features and supported standards

  • XMPP Core: RFC 3920, RFC 6120
  • Client connections over TCP (with TLS/STARTTLS available), Websockets, and HTTP(S) (BOSH).
  • Configurable database backends: MySQL, Postgres, generic ODBC. Mnesia and Redis for transient data.
  • Supports XEPs:
0004 - Data Forms 0012 - Last Activity 0016 - Privacy Lists 0018 - Invisible Presence
0022 - Message Events 0023 - Message Expiration 0030 - Service Discovery 0045 - Multi-User Chat
0049 - Private XML Storage 0050 - Ad-Hoc Commands 0054 - vcard-temp 0055 - Jabber Search
0059 - Result Set Management 0068 - Field Standardization for Data Forms 0073 - Basic IM Protocol Suite 0077 - In-Band Registration
0078 - Non-SASL Authentication 0079 partial - Advanced Message Processin 0082 - XMPP Date and Time Profiles 0083 - Nested Roster Groups
0085 - Chat State Notifications 0086 - Error Condition Mappings 0093 - Roster Item Exchange 0114 - Jabber Component Protocol
0124 - Bidirectional-streams Over Synchronous HTTP (BOSH) 0126 - Invisibility 0138 - Stream Compression 0153 - vCard-Based Avatars
0157 - Contact Addresses for XMPP Services 0160 - Best Practices for Handling Offline Messages 0170 - Recommended Order of Stream Feature Negotiation 0175 - Best Practices for Use of SASL ANONYMOUS
0184 - Message Delivery Receipts 0198 - Stream Management 0199 - XMPP Ping 0202 - Entity Time
0206 - XMPP Over BOSH 0212 - XMPP Basic Server 2008 0237 - Roster Versioning 0279 - Server IP Check
0280 - Message Carbons 0313 - Message Archive Management v0.2

How to build

  1. Requirements.

    To compile MongooseIM you need:

    • GNU Make,
    • GCC,
    • Libexpat 1.95 or higher,
    • Erlang/OTP R15B02 or higher,
    • Reltool 0.5.4 or higher,
    • OpenSSL 0.9.8 or higher, for STARTTLS, SASL and SSL encryption,
    • Zlib 1.2.3 or higher for Stream Compression support (XEP-0138). Optional,
    • PAM library. Optional. For Pluggable Authentication Modules (PAM).
  2. Compiling on UNIX-like systems.

    To compile MongooseIM, go to the main repo directory $REPO and execute the command ($ stands for the shell prompt):

    $ make


    $ ./rebar get-deps
    $ ./rebar compile

    To generate minimal MongooseIM release (without mysql, pgsql or other deps):

    $ make rel


    $ ./rebar generate

    If more advanced relase is required (with mysql or pgsql support) a make configure script with appropirate option(s) has to be run before make rel or ./rebar generate. make configre without any option will print following help message.

    specifies which 3rd party deps will be included in release
    possible options:
    with-mysql  include mysql driver
    with-pgsql  include pgsql driver
    with-odbc   include standard ODBC driver shipped with Erlang/OTP
    with-redis  include redis driver
    with-riak      include riak driver
    with-cassandra  include cassandra driver
    full        include all above deps

    For example if mysql and redis support has to be added to the release, following command has to be run before make rel:

    $ make configure with-mysql with-redis

    The make configure command has to be run only once (unless one need to change the relase config and include some other dependecies).

    Take a look here for instructions how to setup the external databases.

    make rel or ./rebar generate commands will generate a self-contained OTP system image in the project's rel/mongooseim subdirectory. The contents of that directory are as follows:

    • rel/mongooseim/bin - startup/administration scripts,
    • rel/mongooseim/etc - configuration files,
    • rel/mongooseim/lib - MongooseIM binary, header and runtime files,
    • rel/mongooseim/var - spool directory,
    • rel/mongooseim/log - log file directory,
    • rel/mongooseim/releases - release files directory.
  3. Running MongooseIM.

    To run MongooseIM from the project tree after compiling it, change to $REPO/rel/mongooseim.

    There you can use the mongooseim command line administration script to start and stop MongooseIM. For example:

    $ bin/mongooseim start

    will start the server.

    You can also run the server in interactive mode:

    $ bin/mongooseim live

    There's also a tool called mongooseimctl allowing you to perform some operations on a running instance, e.g.:

    $ bin/mongooseimctl status
    The node mongooseim@localhost is started with status: started
    MongooseIM version 1.3.1 is running on that node
  4. Building the testing target and running tests.

    For testing purposes there's a different make target available:

    $ make devrel

    which will generate releases in $REPO/dev/ and prepare them for testing and generating coverage reports.

    To run the tests (from project's root directory, i.e. $REPO):

    $ cd test
    $ make quicktest

    The test results will show up in the console`.

Test suite

In order to test and validate your XMPP servers, here are useful tools:

  • escalus: Erlang XMPP client
  • amoc: a load testing tools

Public testing

Continuous integration:

Code coverage:

Want to get in touch with us?

In case of any suggestions, questions or any thoughts on this project, please feel free to contact us by the standard GitHub ways or at

Want to discuss MongooseIM, problems with your deployement or anything else? Try: