README.rst

Err - the pluggable jabber bot

Err is a plugin based XMPP chatbot designed to be easily deployable, extensible and maintainable.
It allows you to start scripts interactively from your chatrooms for any reason: random humour, starting a build, monitoring commits, triggering alerts ...

It is open source under the GPL3 license.

It is written in python and it is based on jabberbot and yapsy with some minor modifications for the first one.

Community behind the project

Err has a google plus page, feel free to mention it with +err if you need support, have any questions, share some of your creations etc ...
If you have any bug to report or feature suggestion, please log it from its github page.

We strongly encourage you to share your creations, as you will see, a git url is all that you need to share so other people can try out your plugin from err.
If your feature could be interesting as a part of an existing plugin, feel free to fork it on github too.

Features

Tested with hipchat and openfire but should be compatible with any XMPP/Jabber servers.

Can be setup so a restricted list of persons have the administration rights

Dynamic plugin architecture : the bot admin can install/uninstall/enable/disable plugins dynamically just by chatting with the bot.

Supports MUCs (chatrooms)

Can proxy and route one 2 one messages to MUC so it can enable simpler XMPP notifiers to be MUC compatible (for example the jira XMPP notifier).

Really easily extensible (see example below)

Provides an an automatic persistance store per plugin

an !help command that generates dynamically the documentation from the python docstrings of the commands

Prerequisites

It runs under Python 2.7+ under Linux / Windows (since 1.3.0) and Mac.

Create a user for the bot on your private XMPP server or on a public server like jabber.org.
Optionally you can create a MUC (also called conference room or chatroom) in which you can interact with the bot.

Then follow either :

Installation from the sources

Installation from Pypi [Note: This one doesn't work yet under Windows]

Installation from Gentoo Linux

Installation from the sources

Dependencies

Python 2.7+ but probably not 3.0
And those python modules. The copy-paste for the lazy pip users but if you can have them from your standard distro it is better:

pip install -r requirements.txt

Create a user for the bot in your XMPP server admin.

From the installation directory copy:

cp errbot/config-template.py config.py

Read the inline documentation of the file and edit the values so the bot can connect to your XMPP server

Starting the daemon

For a one shot try, I would recommend to use:

./scripts/err.py

Then you can use the -d (or --daemon) parameter to run it in a detached mode.:

./script/err.py -d

so you can inspect the logs for an immediate feedback

Note that config.py needs to be at the root of the working directory of the bot by default.

You can override this behaviour with -c specifying the directory where your config.py is, for example: