Hello kids, in this episode of Sesame Street we learn the letters ‘M’ for MongooseIM, ‘G’ for GroupChat and ‘X’ for XMPP. We assume you should already know letters ‘W’ for WordPress and ‘S’ for (My)SQL and you are just looking for a method to embed a groupchat on your website.
Sure, there are many WordPress plugins for doing this but the ones that allow you to choose your own Jabber server are usually paid or simply don’t match your concept. You can benefit from this tutorial in two ways:
- You already have a chat plugin but you’d like to host your own Jabber server for better control.
- You have some programming skills and you need a guide on how to integrate your custom solution with Jabber.
This tutorial assumes you have no previous knowledge of XMPP and Erlang. Of course it’s always better to know at least some basics but don’t worry – you can make it. :) Also you need to be quite comfortable with Linux console and basic administrative tasks.
Preparing the server
For our setup, we’ll use MongooseIM, which is an ejabberd server fork we developed at Erlang Solutions. The recently released version (1.2.2) doesn’t have a WordPress plugin yet (most probably it will be included in next release) so we’ll need to build MongooseIM from sources. Instructions below are for Fedora 17; They should be similar for any RedHat-based Linux. For Debian/Ubuntu you’ll need to install equivalents of yum’s packages.
OK, I assume you already have WordPress installed and MySQL database created. Important: Auth plugin assumes that your WordPress tables have
Now, follow these steps:
- Install Erlang using the instructions from Erlang Solutions website.
- Install essential packages & tools:
# yum install git gcc expat-devel openssl-devel pam-devel
- Checkout MongooseIM repo:
git clone git://github.com/esl/ejabberd.git
- Checkout WordPress branch:
git checkout wordpress
rel/vars.config and adjust following parameters:
hosts: can by anything but most convenient would be the same domain as your website has
%% at the beginning and enter your WordPress database config; it is recommended to create separate user just for MongooseIM and limit its privileges to read-only, but using the same account both for WordPress and Jabber will work just fine
auth_method: set it to
[wordpress, internal] or
[wordpress, anonymous, internal], should you need to allow guests to access the chat
wp_logged_in_salt: enter exactly the same values as you’ve entered in
make rel and wait… :)
- Now in folder
rel/ejabberd you have a standalone MongooseIM instance ready to be used with both ordinary Jabber clients, Websockets or BOSH (AJAX calls encapsulating Jabber requests); you can move this folder anywhere you want and start it with any user
- You can start the server with
rel/ejabberd/bin/ejabberd start and stop with
What about SSL?
Adding SSL support requires some additional steps. Let’s say you have your certificate already or use steps 1-4 from this site to create self-signed one. You’ll need to prepare three files (all in PEM format):
- with both private key certificate; if you used tutorial above, do
cat server.crt server.key > server.pem
Private key in this file must not be protected by password
- with private key only (
- with certificate only (
You may keep them anywhere you want, as long as the user running MongooseIM has read privileges for them. Now we start with editing
%% at the beginning and set path to the file with both private key and certificate
%% (don’t remove the comma, it’s there on purpose!) and enter paths to the files plus key password
BOSH doesn’t support SSL connections yet, so above configuration is for ordinary Jabber connection and Websockets.
And it’s done! Now you can execute
make rel again to rebuild the release. If you get following error during rebuild:
ERROR: Failed to generate target from spec: "copy file /usr/lib/
erlang/erts-184.108.40.206/bin/epmd -> /home/mongoose/ejabberd/rel/
ejabberd/erts-220.127.116.11/bin/epmd: text file or pseudo-device busy\n"
ERROR: Unexpected error: rebar_abort
ERROR: generate failed while processing /home/mongoose/ejabberd/rel:
killall epmd and don’t worry. :)
Here are ports used by MongooseIM. You might need them for configuring your client and firewall.
Ordinary Jabber: 5222
Websockets Secure: 5289
The easiest way to manage rooms is to use ordinary Jabber client to connect to the server. My personal choice for development is Psi, as it comes with good XML Console but any other will also do the trick.
- Install Psi client. Assuming you’re using some graphical environment on your Fedora box:
# yum install psi
- On first launch Psi will ask you if you want to create an account. Choose option for existing account.
- If such startup window didn’t pop up, navigate to
General->Account Setup and press
- Call your new account whatever you like, for example “Site Admin”
- Your Jabber ID is
[Wordpress admin username]@[XMPP domain], e.g.
- Your Password is the same as you use for WordPress account
- If you haven’t enabled SSL in MongooseIM config, switch to
Connection tab and in
Allow plaintext authentication select
- Now go online and after Psi connects, select
- Your Host is
muc.[XMPP domain], e.g.
- Choose any room name and nickname you like and click
- In new window click a button with an arrow pointing down (it’s in upper right corner) and select
- Switch to
General tab. Most default settings are nice enough but it’s important to
Make room persistent and set some room title. Then click
Repeat above steps with joining a room and configuring it for every room you’d like to be available for your users. There you go! Now the only thing left is to configure web client…
Connecting with ordinary Jabber client is easy. Enter username, domain, password and you’re there. But what if we would like to integrate chat with WordPress (or any other CMS/MVC framework) session system?
Good news: we can use “logged in” cookie! The name is
wordpress_logged_in_[site name hash here]. The bad news is, it’s
- Clone MUCkl repository (original software created by Stefan Strigler, my fork modified it a bit for sake of this tutorial):
git clone git://github.com/fenek/MUCkl.git
- Clone JSJaC repository:
git clone git://github.com/sstrigler/JSJaC.git
- Enter JSJaC directory and just run
- Enter MUCkl directory and create config file:
cp config.js.example config.js
- Edit configuration:
BACKENDTYPE: set it to
binding if you’d like to have the same chat open across multiple pages or
websockets if your groupchat is designed to be unique for specific page (e.g. discussion under video stream) and you don’t care if users of some browsers won’t be able to use your chat.
HTTPBASE: should be
http://your.host.name:5280/http-bind/ or if you’ve chosen to use Websockets:
ws://your.host.name:5288/ws-xmpp (should begin with
wss:// if you configured SSL)
XMPPDOMAIN: set it to the same value as you’ve entered in
AUTHTYPE: set it to
sasl if you want to login with username and password or
saslanon for anonymous authentication; you can also make the value generated by PHP based on user status:
if($user_login == '')
$authtype = 'saslanon';
$authtype = 'sasl';
var AUTHTYPE='<?php echo $authtype; ?>';
MUCKLPASS: if you’re using
saslanon authentication, you don’t need to bother with it; you can hardcode this parameter but the best solution is to generate values (again) with PHP:
var MUCKLJID='<?php echo $user_login; ?>';
var MUCKLPASS='<?php echo $_COOKIE["wordpress_logged_in_"
MUCKLPASS: this will be specific user's nick in rooms; You can always set it to:
var MUCKLNICK = MUCKLJID;
ROOMS: Using the template in config file, create a list of rooms to which your users will be able to connect; default
server for your setup is
- Done! If you chose to use some PHP, follow steps below. If not, you can open
muckl.html in your browser and enjoy your chat. :)
- Easiest way of embedding the groupchat in WordPress page is to insert
iframe into post/page content:
<iframe style="display: block; width: 966px; height: 400px;"
[room ID] is the sequence number of room entry in
config.js starting at 0; if you want to allow users to choose room, just skip
?room= in URL
What if I used PHP in config file?
- First of all, you need to rename
- Replace old config file name in
- At the beginning of
- Copy MUCkl folder into WordPress root dir
That's all. Maybe it's not a short process but unfortunately custom solutions always cost more time than generic ones. This is not the last post about MongooseIM & Web integration. Next one will describe some more advanced aspects of configuration and another will cover WordPress plugin still under development, which you may observe already as Erlang Central Cafe chatbox.
The only downside of the current
wordpress branch is that the groupchat module there is experimental and even though it passes unit tests, it is still not considered stable yet. The "experimental" part is possibility of single user joining room from multiple tabs but with the same nick. Original groupchat module doesn't allow such behaviour and as you might guess - it is quite vital.
Have a nice programming session! ;)