valeriansaliou edited this page Sep 17, 2014 · 21 revisions

The BOSH Server

Okay, we're at the most important part of your installation! You've got two choices: you can use the official Jappix BOSH server or use your own BOSH server (more recommended, you should not rely on an external service).

Please note that your BOSH server should take the CORS specification in charge. Metronome's BOSH, Prosody's one, ejabberd's one, node-xmpp-bosh, Punjab and Palladium work fine with this, but Openfire one doesn't seem to have support for this (in this case, you will need to use a proxy).

1. Use the official Jappix BOSH server

The official Jappix binding (or BOSH) server is available at this address:

Note: this is not an open BOSH server. You can only connect to a XMPP account through it. Consider using your own BOSH server for your own Jappix setup (see below).

 2. Use your own BOSH server

There are two BOSH servers types, that we call local and open. Please consider that the local BOSH servers will only allow local connections. It means that, if my XMPP domain is and a friend wants to connect his XMPP domain through my own Jappix installation, it will be impossible. On the contrary, the open BOSH servers will allow connections to any domain, local and through the Internet.

Metronome (local)

In the Metronome configuration file, add the following code to your modules list:

modules_enabled = {
  "bosh"; -- Enable mod_bosh

The best BOSH configuration for Jappix is as following (define it in the global section):

-- BOSH configuration (mod_bosh)
bosh_max_inactivity = 30
cross_domain_bosh = true

If serving BOSH on a BOSH-only (or non-XMPP) host, define a new component (you need to load mod_bosh both in global configuration and component configuration):

---Set up a BOSH service
Component "" "http"
    modules_enabled = { "bosh" }

ejabberd (local)

The ejabberd's BOSH module can be enabled by adding a request handler on a socket listener:

{5280, ejabberd_http, [
      {["http-bind"], mod_http_bind}

Then, enable the mod_http_bind in the modules configuration section:

{mod_http_bind, []}

You can change the maximum inactivity value:

                   {max_inactivity, 60}   % default value = 30s

For further informations, you can read the official ejabberd's mod_http_bind documentation page.

Prosody (local)

In the Prosody configuration file, add the following code to your modules list:

modules_enabled = {
  "bosh"; -- Enable mod_bosh

To allow cross-domain access (also known as CORS), add the following piece of code to your configuration file:

cross_domain_bosh = true

For further informations, you can read the official Prosody's BOSH module documentation page.

Openfire (local)

  1. Login to the administration console
  2. Go to Server SettingsHTTP Binding
  3. Check the Enabled box
  4. Remember the port number, which should be 7070 (you should change it to 5280, which is standard)

Note: it is known that Jappix Mini will not work correctly using Openfire's internal BOSH. If you want to use Jappix Mini, you'd better use an external BOSH server, like node-xmpp-bosh!

 node-xmpp-bosh (open)

node-xmpp-bosh is based on the nodejs library. It makes it hard to install but really lightweight. Only advanced users with strong UNIX knowledges may install it, but we recommend it for its scalability.

Download node-xmpp-bosh from the project page.

Then, extract the package you just downloaded and open the INSTALL.txt file. Read carefully the instructions to setup node-xmpp-bosh on your server. It is recommended to compile your own nodejs, and then add manually the required plugins in the nodejs folder.

Be sure to set the option pidgin_compatible to false (pidgin_compatible: false) for stability purposes.

With lots of users connecting and disconnecting, node-xmpp-bosh may consume more and more CPU and RAM with the time. This can make your server crash after 2 weeks, even though the global current connection is the same during these 2 weeks (can be more time). You should add a cronjob to restart node-xmpp-bosh every monday at 4:30am (or everyday).

Note: those who are using a Debian or a Debian-based system (Ubuntu) may be interested in the how-to we wrote for them, which makes the installation even simpler!

Warning: if node-xmpp-bosh crashes when calling the StartTLS functions, you may consider using an older nodejs (version 0.4.7 is recommended) in replacement of the latest version you got (in which the TLS API was changed). See this bug report for more information.

The latest version of node-xmpp-bosh handles TLS for all versions of node.js >= 0.4.2 correctly, but it is recommended that you use the latest stable version. If you are having blank pages issues on BOSH (empty HTTP responses) after a while, make sure that you upgrade to the latest stable node.js release.

 Punjab (open)

Notice: you need to get the last Punjab GIT version for this (upper than 0.14), because of a XML parsing bug (xml:lang used by Jappix), which will abort your session when connected.

Go to Punjab repository and grab latest version. Follow instructions in INSTALL.txt, it may include the installation of some python-twisted dependencies. Then create a TAC file, e.g. punjab.tac:

# punjab tac file
from twisted.web import server, resource, static
from twisted.application import service, internet

from punjab.httpb  import Httpb, HttpbService

root = static.File("./html") # a static html directory

b = resource.IResource(HttpbService())
root.putChild('http-bind', b) # url for BOSH

site  = server.Site(root)

application = service.Application("punjab")
internet.TCPServer(5280, site).setServiceParent(application)

And run:

twistd -y punjab.tac

Now your BOSH server is listening on port 5280, and you must reach it through the /http-bind path, e.g. http://localhost:5280/http-bind

 Palladium (open)

The Jappix authors are also developing a free BOSH servlet for the Tomcat server: Palladium.

If you would like to use it, please go to the project page.

3. Optionally setup a proxy server

If you want to use Jappix through firewalls (in companies for instance), you will need to use a proxy:

 Apache proxy

Configure your Apache host with something like this:

a2enmod proxy_http
a2enmod headers
/etc/init.d/apache2 restart
ProxyPass  /
ProxyPassReverse  /
Header set Access-Control-Allow-Origin "*"

Don't forget this last line, it can be source of many problems. For more securtiy, * can be replace by your domain.

Lighttpd proxy

Enable the mod_rewrite and mod_proxy for your Lighttpd server, and add this in your configuration:

$HTTP["host"] == "" {
        url.rewrite-once = ( "^/bind" => "/http-bind" )
        proxy.server  = ( "/bind" => ( ( "host" => "", "port" => 5280 ) ) )

 Nginx proxy

Add this in your configuration:

location /http-bind/ {
        proxy_set_header Host $host;
        proxy_buffering off;
        tcp_nodelay on;

You're done!