177 lines
6.1 KiB
ReStructuredText
177 lines
6.1 KiB
ReStructuredText
.. image:: http://gbin.github.com/err/images/err.png
|
|
:align: right
|
|
|
|
Err - the pluggable chatbot
|
|
===========================
|
|
|
|
Err is a plugin based 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 and extensible in python and it is based on yapsy_ with an heavily adapted jabberbot_ for the XMPP backend.
|
|
|
|
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
|
|
--------
|
|
|
|
Backends :
|
|
|
|
- XMPP : Tested with hipchat_, openfire_ and Jabber but should be compatible with any standard XMPP servers.
|
|
- CampFire support
|
|
- Basic IRC support
|
|
- Supports MUCs (chatrooms)
|
|
- Local Graphical Console (for testing/dev)
|
|
- Local Text Console (for testing/dev)
|
|
|
|
Included :
|
|
|
|
- an !help command that generates dynamically the documentation from the python docstrings of the commands
|
|
- A command history system where the users can recall a previous command
|
|
- 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).
|
|
|
|
Administration and Security :
|
|
|
|
- Can be setup so a restricted list of persons have the administration rights
|
|
- Dynamic plugin architecture : the bot admin can install/uninstall/update/enable/disable plugins dynamically just by chatting with the bot.
|
|
- Plugins can be hosted publicly or privately on git
|
|
- Plugins can be configured directly from the chat (no need to change setup files for every plugin)
|
|
- Configs can be exported and reimported (!export)
|
|
- Technical logs can be inspected from the chat
|
|
|
|
Provides for Extensibility :
|
|
|
|
- a really easy learning curve for you to write your first plugin (see example below)
|
|
- test consoles for superfast developement roundtrips
|
|
- a support for subcommands
|
|
- an automatic persistance store per plugin
|
|
- a really simple webhooks integration
|
|
- a polling framework for the plugins
|
|
- an easy configuration framework
|
|
- a templating framework to display fancy HTML messages
|
|
- an automatic conversion from HTML to plaintext when the backend doesn't support it (you don't have to make 2 versions of your command output)
|
|
|
|
|
|
.. _hipchat: http://www.hipchat.org/
|
|
.. _openfire: http://www.igniterealtime.org/projects/openfire/
|
|
.. _jabberbot: http://thp.io/2007/python-jabberbot/
|
|
.. _yapsy: http://yapsy.sourceforge.net/
|
|
.. _`google plus page`: https://plus.google.com/101905029512356212669/
|
|
.. _github: http://github.com/gbin/err/
|
|
|
|
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::
|
|
|
|
./script/err.py -c /etc/err
|
|
|
|
More details on the bot admin features can be found on the wiki : https://github.com/gbin/err/wiki
|
|
|
|
Installation from pypi
|
|
----------------------
|
|
|
|
Pip will take care of installing err and the basic dependencies for you:
|
|
pip install err
|
|
|
|
Go to or create a working directory for it then copy there and adapt the configuration template::
|
|
|
|
cp /usr/lib64/python2.7/site-packages/errbot/config-template.py config.py
|
|
|
|
Then you can start and try your bot::
|
|
|
|
err.py
|
|
|
|
Installation from gentoo
|
|
------------------------
|
|
It has been merged to the main tree.
|
|
|
|
So the standard way: ::
|
|
|
|
emerge net-im/err
|
|
|
|
Interact with the Bot
|
|
---------------------
|
|
|
|
- Invite the bot directly from your chat client.
|
|
- Send "!help" to it without the quotes
|
|
- it should answer by the list of available commands and a short explanation
|
|
- if you want to know more about a specific command you can do "!help command"
|
|
|
|
More documentation is available on the wiki : https://github.com/gbin/err/wiki
|
|
|
|
Install/uninstall a public known plugin
|
|
---------------------------------------
|
|
|
|
To get a list of public repo you can do::
|
|
|
|
!repos
|
|
|
|
Then pick one that you fancy for example::
|
|
|
|
!install err-pollbot
|
|
|
|
You should have instantly a new poll service you can use to vote for where to lunch with you collegues :)
|
|
|
|
You can imply uninstall a plugin by its name:
|
|
!uninstall err-pollbot
|
|
|
|
Note: Please pay attention when you install a plugin, it may require more python external dependencies.
|
|
|
|
Tutorial to write a simple plugin
|
|
---------------------------------
|
|
|
|
Try it ! It is super simple !
|
|
|
|
You can find a tutorial here : https://github.com/gbin/err/wiki/plugin-dev
|
|
|