Requirements
============

- Python 2.7.x
- Twisted >= 15.2.0:
   - Twisted Core
   - Twisted Words
- Wokkel >= 0.7.1 (http://wokkel.ik.nu/)
- A XMPP server that supports the component protocol (XEP-0114),
  and, to enable the micro-blogging feature, Namespace Delegation (XEP-0355)
  and privileged entity (XEP-0356) are needed.
  We recommend using Prosody with mod_privilege and mod_delegation modules.
- SàT backend (http://repos.goffi.org/sat) is currently needed for MAM and RSM handling

For the PostgreSQL backend, the following is also required:

- PostgreSQL (including development files for psycopg2)
- psycopg2


Installation
============

sat_pubsub uses setuptools for package building and installing.
To build from the source run:

  python setup.py build

Then, to install run the following, possibly as root:

  python setup.py install

See the setuptools documentation for further information on changing
installation locations.


Configuration
=============

sat_pubsub uses Twisted's twistd command for running its services.

Idavoll, on which sat_pubsub is based, provides two types of storage for the backend:
a memory-based storage facility, which is volatile, and a persistent storage facility
using PostgreSQL. For now, sat_pubsub only uses the persistent storage facility.

For using the PostgreSQL backend, create a database (for example named pubsub):

  sudo -u postgres createuser -d -P `whoami`
  createdb pubsub
  psql pubsub < sat_pubsub/db/pubsub.sql


Your XMPP server must also be configured to accept component connections and,
to enable the micro-blogging feature, privileged entity and namespace delegation.
See below for details.


Running sat_pubsub
==================

The minimal example for running sat_pubsub is:

  twistd sat_pubsub

This will start the service and run it in the background. It generates a
file twistd.pid that holds the PID of the service and a log file twistd.log.
The twistd utility has a fair number of options that might be useful, and
can be viewed with:

  twistd --help

When the service starts, it will connect to the XMPP server at the local
machine using the component protocol, and assumes the JID 'pubsub'. This
assumes a couple of defaults which can be overridden by passing parameters to
the twistd plugin. You can get an overview of the parameters and their defaults
using:

  twistd sat_pubsub --help

In particular, the following parameters will be of interest:

 --jid: The Jabber ID the component will assume.
 --rport: the port number of the XMPP server to connect to
 --secret: the secret used to authenticate with the XMPP server.

For example:

  twistd sat_pubsub --jid=sat-pubsub.<your_xmpp_domain> --secret=<password>

You may also want to provide the --verbose flag to see the traffic flow,
for example to debug the configuration. Below some specifics for the
Prosody XMPP server implementation.


Running sat_pubsub with Prosody
===============================

To enable the micro-blogging feature with Prosody XMPP server, you need
the mod_delegation and privileged_entity plugins.
Check if the mod_delegation and mod_privilege plugins are already
in your Prosody installation:

  cd prosody/plugins
  ls mod_delegation.lua
  ls mod_privilege.lua

If you can't see it, download them from http://modules.prosody.im:

  wget http://hg.prosody.im/prosody-modules/raw-file/tip/mod_delegation/mod_delegation.lua
  wget http://hg.prosody.im/prosody-modules/raw-file/tip/mod_privilege/mod_privilege.lua

Edit the prosody.cfg.lua file to add this module:

  modules_enabled = {
                [...]
                "delegation";
                "privilege";
                [...]
  }

In your VirtualHost, add this lines:

VirtualHost "<your_xmpp_domain>"
  privileged_entities = {
    ["sat-pubsub.<your_xmpp_domain>"] = {
      roster = "get";
      message = "outgoing";
    },
  }
  delegations = {
    ["urn:xmpp:mam:1"] = {
      filtering = {"node"};
      jid = "sat-pubsub.<your_xmpp_domain>";
    },
    ["http://jabber.org/protocol/pubsub"] = {
      jid = "sat-pubsub.<your_xmpp_domain>";
    },
  }

Also add these two lines at the end of the file, adapting them to your XMPP server
domain (virtual host) and selecting a password of your choice:

  Component "sat-pubsub.<your_xmpp_domain>"
          component_secret = "<password>"
		  modules_enabled = {"delegation", "privilege"}

For a more complete installation and configuration of Prosody to be used with
sat_pubsub, please report yourself to the Salut à Toi wiki:

http://wiki.goffi.org/wiki/Libervia/en#XMPP_server