jarn.xmpp.core 0.1a2

Buildout

A sample buildout you can use as a starting point can be found at jarn.xmpp.buildout. Wokkel on which jarn.xmpp.twisted depends upon has not had a release for a while, so you will need to either use a development version or add:

find-links = http://dist.jarn.com/public

to your buildout to get an updated version.

Setting up ejabberd (>=2.1.5)

• Download the ejabberd installer

• We assume that your xmpp domain is myserver. There should exist an administrator account admin@myserver. In addition if you intend to run some of the tests in any of the jarn.xmpp.* packages you will need to be running an additional XMPP node on localhost. You can safely remove any references to localhost if you are not interested in doing that.

• You will need two hosts (one if you are not running tests, see above).

  {hosts, ["myserver", "localhost"]}.

• Make sure you have enabled the http_bind module, as this is what the javascript clients will use to connect. You should have something like this in your ejabberd.cfg:

  {5280, ejabberd_http, [
       http_bind,
       web_admin
       ]}

• Because ejabberd’s implementation of XEP-0060 is not standard use of the ejabberd’s dag module is necessary. So, make sure your pubsub module is configured appropriately:

  {mod_pubsub,   [
      {access_createnode, pubsub_createnode},
      {ignore_pep_from_offline, true},
      {last_item_cache, false},
      {nodetree, "dag"},
      {plugins, ["dag", "flat", "hometree", "pep"]}
      ]},

• In order to test and run custom XMPP components (for instance the collaborative editing component provided by jarn.xmpp.collaboration) you will need to allow them to connect. This means you should have something similar to this configuration:

  {5347, ejabberd_service, [
            {access, all},
            {shaper_rule, fast},
            {ip, {127, 0, 0, 1}},
            {hosts,
             ["collaboration.myserver",
              "collaboration.localhost"],
             [{password, "secret"}]
            }
           ]},

The rest of the standard options should be fine. In any case a sample ejabberd.cfg is included in the jarn.xmpp.buildout package.

Test that you can access your ejabberd by logging to the admin interface (typically http://host:5280/admin). You should also be able to access the http-bind interface at http://host:5280/http-bind.

Setting up your front-end proxy

On the client-side every authenticated user will be connected to your jabber server through an emulated bidirectional stream through HTTP. To allow for this you need a proxy in front of Plone that will be redirecting the XMPP stream to your XMPP server. It is possible to do without one using the inferior solution of Flash plugins but this is not going to be supported.

So assuming you run nginx as a proxy at port 80 for the domain myserver, Plone listens on 8081 and your ejabberd has the http_bind configured for port 5280, your nginx configuration will look like this:

http {
    server {
        listen       80;
        server_name  myserver;

        location ~ ^/http-bind/ {
            proxy_pass http://myserver:5280;
        }

        location / {
            proxy_pass http://myserver:8081/VirtualHostBase/http/myserver:80/Plone/VirtualHostRoot/;
        }

    }
  }

Again, it might help you to have a look at the sample buildout provided in jarn.xmpp.buildout.

Setting up your Plone instances

Your instances will need to maintain a connection to the administrator account of your XMPP server. This is accomplished through Twisted and you will need to run a Twisted reactor on each of them. To do so include this in your instance section of your buildout:

zcml-additional =
  <configure xmlns="http://namespaces.zope.org/zope">
    <include package="jarn.xmpp.twisted" file="reactor.zcml" />
  </configure>

Again, use jarn.xmpp.buildout as a starting point!

Setting up a new Plone site

• Start ejabberd

• Start the Nginx frontend. sudo bin/frontend start

• Start your zope instance.

• Access Zope via Nginx http://myserver/ and create a new Plone site with jarn.xmpp.core.

• Go to the Plone control panel, into the registry settings. Edit the jarn.xmpp.* settings to reflect your installation, passwords etc.

• Restart your Plone instance.

• Upon the first request the administrator will log to his account. You should see things happening in the logs and if there are any errors something might be wrong with your installation.

• Setup the the users and pubsub nodes. You do this by calling @@setup-xmpp like http://myserver/@@setup-xmpp. The form will not report any errors as everything will happen asynchronously but you will get the results/failures on the console.

If you are going to use this on an existing site, you only need to perform the last step after making sure that your XMPP admin is connected.

Setup

• Add a few users.

• Add the Online users portlet.

• Add a Pubsub node portlet, where the node name is people and the type is collection. This is the collective feed of all users.

• For each user you added add a Pubsub node portlet, where the node name is the user’s id and the type is leaf. This is the personal feed of the respective user.

Usage

• Login several users in different browsers.

• On the online users portlet click on a user. This allows you to message him and he can start a chat session.

• Each user is able to post a message to his node. Others will receive in real time. The portlets will be updated on the next request.

0.1a2 - 2010-05-11

• Updated documentation on how to add a recent wokkel. [ggozad]

0.1a1 - 2010-05-09

• Initial release [ggozad]