In this short guide we will set MongooseIM up and get users chatting right away. The goal is to get to know MongooseIM, set it up, go through basic operations and validation.
Warning: This setup is not intended for production.
Note: This procedure has been tested on an Ubuntu 18.04.x LTS.
We recommend, you install mongooseIM binaries from a package Erlang Solutions delivers.
Alternatively, check out our tutorial on How to build MongooseIM from source code for an introduction to compiling, building and testing MongooseIM.
Download a package
Go to the downloads section of the Erlang Solutions website, and choose the version of MongooseIM you want. The following sections describe the installation process for different operating systems.
Ubuntu and Debian
Once the deb file is downloaded, open a terminal window and navigate to the directory containing the package. Use the following command to unpack and install MongooseIM:
An ODBC (RDBMS) driver must be installed on your machine to unpack and install from RPM packages. Enter the following command in a terminal window to install the latest unixODBC driver:
Warning: MongooseIM will use its default database - Mnesia, which is faster and simpler to setup, but not intended for production purposes when it comes to persistent data.
Note: It is possible at anytime to use external databases. For more information see the end of this guide.
The following command will start the MongooseIM server:
When you change the config file and want to restart the MongooseIM server:
Use the following command to stop the MongooseIM server:
At any given time, the following command shows the status of a MongooseIM server:
nodedownthen MongooseIM is not running. Else it will show its status
stopping, and its version.
When needed, you can also launch the server in the interactive mode:
For running MongooseIM in a non-interactive way within a supervision system (e.g. systemd), it is recommended to use the foreground mode:
You can check server loglevel:
Run bootstrap scripts for initial configuration:
It executes scripts inside the
scripts/ directory with a
bootstrap prefix in alphabetical order. More information
Hello from the
scripts/bootstrap01-hello.sh script that you can find in the release directory
Registering (creating) users
The default XMPP domain served by MongooseIM right after installation is
You can register (create) users with the
This command registers the user
user@domain using password
1 2 3 4
You can check that it has correctly been created:
1 2 3 4
Now you can list all registered users in your host:
If you want delete users in your host:
Populate the contact lists (rosters)
For a given user (
localserver), add a contact (
subsparameter is the "subscription" to a user's presence. Possible values are:
both. A subscription in
both direction means each user will receive each other's presence.
Verify the contact list:
1 2 3
Basic MongooseIM configuration
You can edit the
Warning: We recommend you do not touch the advanced settings at this stage.
For each change, edit the configuration file using the right Linux/Unix user. Save (and optionally backup, archive, or version) the configuration file and restart the MongooseIM server.
Set your own loglevel in the configuration file:
Save and exit your editor, restart MongooseIM and check your loglevel from the command line:
You can use commands such
In order to see live logs:
MUC (Multi-User Chat) for groupchats
Enable MUC, or Multi-User Chat, for groupchats/channels in the
1 2 3 4
1 2 3 4 5 6 7
For faster contact list downloads at each client/app (re)connection, edit the configuration file:
1 2 3
1 2 3 4 5
Read and double-check your configuration in a different way, after starting MongooseIM:
If MongooseIM does not start because the configuration file is broken in some way:
Using an XMPP/Jabber client/app
The following steps use the registered users on the MongooseIM server, done above.
Users that are registered on your server can now add their accounts in a chat application like Gajim (specifying either the server’s IP address or domain name), and start chatting!
Note about session conflicts
If you're going to connect several clients with the same username and domain (for example a phone and a laptop), please make sure they are using different resource names (a kind of device/client identifier). This should be configurable in the account settings of every XMPP client.
Otherwise, the clients will keep disconnecting each other, because MongooseIM always terminates the older session in case of a conflict.
Gajim is available on Ubuntu, CentOS & Windows.
Warning: Gajim has an obsolete UX. However, it is still well maintained, and has a console that is extremely useful for debugging and testing/validation purposes at the XMPP protocol level.
- Launch Gajim. Ignore the window with Plugin updates.
- Go to Edit -> Accounts.
- Click Add in the left part of the window and select I already have an account I want to use, click Forward
- Enter the user, domain and password for the accounts registered previously on the command line
- Click Forward and then Finish
- Ignore the TLS/SSL error/warning and continue
- Close the Account window.
Add your three created users:
Check what users are currently connected:
Chat with another person
alice's account to send messages directly to
bob and use
bob's account to reply directly to
From the MongooseIM command line:
alice's account to create a groupchat
channel on your
muc.localhost service, and configure it by making it persistent. Invite
carol's accounts, accept the invitation and join the
channel groupchat. All three users exchange messages.
carol's account to add
bob to her contact list. Use
bob's accounts accept those additions.
Verify on the MongooseIM server:
1 2 3
alice's profile (vCard) in Gajim: Modify Account..., then Profile, just set her Name to
Verify on the MongooseIM server:
Now you have the minimum knowledge: you know how to deploy MongooseIM, configure some basic features, check/verify a few useful items, validate it both on the client and server side, and utilize a few good practices.
Summary: command line
mongooseimctl, with commands such as:
You can even run
mongooseimctl without arguments for a list of available commands.
You know basic entries in the files:
In an app, you know how to:
- chat with another user
- create/join groupchats
- manage contact lists (roster)
- edit profile (vCard)
For the next steps, we now encourage you to:
- Deploy it as a single node, on a publicly accessible server, with a real routable domain name with its certificate
- Add an RDBMS for persistent data, and LDAP for user directory
- Enable message history with MAM (Message Archive Management)
- Enable file exchange with HTTP file upload, with an S3-compatible object storage server
- Use a mobile app for users to chat