README.rst 9.09 KB
Newer Older
Guillaume Binet's avatar
Guillaume Binet committed
1

2
.. image:: https://img.shields.io/travis/gbin/err/master.svg
Guillaume Binet's avatar
Guillaume Binet committed
3
   :target: https://travis-ci.org/gbin/err/
Guillaume Binet's avatar
Guillaume Binet committed
4

5
.. image:: https://img.shields.io/pypi/v/err.svg
Guillaume Binet's avatar
Guillaume Binet committed
6 7 8
   :target: https://pypi.python.org/pypi/err
   :alt: Latest Version

9
.. image:: https://img.shields.io/pypi/dm/err.svg
Guillaume Binet's avatar
Guillaume Binet committed
10 11 12
   :target: https://pypi.python.org/pypi/err
   :alt: Downloads

13
.. image:: https://img.shields.io/github/license/gbin/err.svg
Guillaume Binet's avatar
Guillaume Binet committed
14
   :target: https://pypi.python.org/pypi/err
Guillaume Binet's avatar
Guillaume Binet committed
15
   :alt: License
Guillaume Binet's avatar
Guillaume Binet committed
16

17 18 19 20
.. image:: https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg
   :target: https://gitter.im/gbin/err?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge 
   :alt: Join the chat at https://gitter.im/gbin/err

21 22 23 24 25 26
|
|

.. image:: http://gbin.github.io/err/_static/err_speech.png
   :target: http://errbot.net

Guillaume Binet's avatar
Guillaume Binet committed
27

28 29
Err
===
Guillaume BINET's avatar
Guillaume BINET committed
30

31
Err is a chatbot. It allows you to start scripts interactively from your chatrooms
Guillaume Binet's avatar
Guillaume Binet committed
32
for any reason: random humour, chatops, starting a build, monitoring commits, triggering
33
alerts...
34

35
It is written and easily extensible in Python.
36

37
Err is available as open source software and released under the GPL v3 license.
Guillaume BINET's avatar
Guillaume BINET committed
38 39


40 41
Features
--------
Guillaume BINET's avatar
Guillaume BINET committed
42

43
**Chat servers support**
Guillaume Binet's avatar
Guillaume Binet committed
44

45 46
- `Slack <https://slack.com/>`_ (built-in support)
- `Hipchat <http://www.hipchat.org/>`_ (built-in support)
Guillaume Binet's avatar
Guillaume Binet committed
47
- `Telegram <https://www.telegram.org/>`_ (built-in support)
48 49 50 51 52
- `XMPP <http://xmpp.org>`_ (built-in support)
- IRC (built-in support)
- `Gitter <https://gitter.im/>`_ (Follow the instructions from `here <https://github.com/gbin/err-backend-gitter>`_ to install it)
- `CampFire <https://campfirenow.com/>`_ (Follow the instructions from `here <https://github.com/gbin/err-backend-campfire>`_ to install it)
- `TOX <https://tox.im/>`_ (Follow the instructions from `here <https://github.com/gbin/err-backend-tox>`_ to install it)
Guillaume BINET's avatar
Guillaume BINET committed
53

54
**Administration**
Guillaume BINET's avatar
Guillaume BINET committed
55

56
After the initial installation and security setup, Err can be administered by just chatting to the bot.
Guillaume BINET's avatar
Guillaume BINET committed
57

58 59 60 61 62 63
- install/uninstall/update/enable/disable private or public plugins hosted on git
- plugins can be configured from chat
- direct the bot to join/leave Multi User Chatrooms (MUC)
- Security: ACL control feature (admin/user rights per command)
- backup: an integrated command !backup creates a full export of persisted data.
- logs: can be inspected from chat or streamed to `Sentry <https://github.com/gbin/err/wiki/Logging-with-Sentry>`_
Guillaume BINET's avatar
Guillaume BINET committed
64

65
**Developer features**
Guillaume BINET's avatar
Guillaume BINET committed
66

67 68 69 70 71 72 73 74 75
- Presetup storage for every plugin i.e. ``self['foo'] = 'bar'`` persists the value. 
- Webhook callbacks support
- supports `markdown extras <https://pythonhosted.org/Markdown/extensions/extra.html>`_ formatting with tables, embedded images, links etc.
- configuration helper to allow your plugin to be configured by chat
- Graphical and text development/debug consoles
- Self-documenting: your docstrings becomes help automatically
- subcommands and various arg parsing options are available (re, command line type)
- polling support: your can setup a plugin to periodically do something
- end to end test backend
Guillaume BINET's avatar
Guillaume BINET committed
76

77 78 79
Community and support
---------------------

80
If you have a question or want to share your latest plugin creation: feel free to join the chat on `gitter <https://gitter.im/gbin/err>`_. Err has also a `google plus community <https://plus.google.com/b/101905029512356212669/communities/117050256560830486288>`_. You can ping us on Twitter with the hashtag ``#errbot``. 
81 82 83
But if you have a bug to report or wish to request a feature, please log them `here <https://github.com/gbin/err/issues>`_.

Contributions
84
-------------
85

86 87 88 89
Feel free to fork and propose changes on `github <https://www.github.com/gbin/err>`_

Prerequisites
-------------
90

91
Err runs under Python 3.3+ and Python 2.7 on Linux, Windows and Mac. For some chatting systems you'll need a key or a login for your bot to access it.
Guillaume BINET's avatar
Guillaume BINET committed
92

Nick Groenen's avatar
Nick Groenen committed
93 94
Installation
------------
95

96 97 98
If you can, we recommend to setup a `virtualenv <https://pypi.python.org/pypi/virtualenv>`_.

Err may be installed directly from PyPi using pip by issuing::
99

Nick Groenen's avatar
Nick Groenen committed
100
    pip install err
Guillaume BINET's avatar
Guillaume BINET committed
101

Nick Groenen's avatar
Nick Groenen committed
102
Or if you wish to try out the latest, bleeding edge version::
Guillaume BINET's avatar
Guillaume BINET committed
103

Nick Groenen's avatar
Nick Groenen committed
104
    pip install https://github.com/gbin/err/archive/master.zip
105

Guillaume BINET's avatar
Guillaume BINET committed
106

Nick Groenen's avatar
Nick Groenen committed
107
**Extra dependencies**
Guillaume BINET's avatar
Guillaume BINET committed
108

109
setup.py only installs the bare minimum dependencies needed to run Err.
Nick Groenen's avatar
Nick Groenen committed
110
Depending on the backend you choose, additional requirements need to be installed.
111

112 113 114 115 116 117 118
+------------+-----------------------------------------------------------------------------------+
| Backend    | Extra dependencies                                                                | 
+============+===================================================================================+ 
| Slack      | - ``slackclient``                                                                 | 
+------------+-----------------------------------------------------------------------------------+
| XMPP       | - ``sleekxmpp``                                                                   | 
|            | - ``pyasn1``                                                                      | 
Guillaume Binet's avatar
Guillaume Binet committed
119
|            | - ``pyasn1-modules``                                                               | 
120 121 122 123 124 125 126 127 128
|            | - ``dnspython3`` (py3)                                                            | 
|            | - ``dnspython``  (py2)                                                            | 
+------------+-----------------------------------------------------------------------------------+
| Hipchat    | XMPP + ``hypchat``                                                                |
+------------+-----------------------------------------------------------------------------------+
| irc        | - ``irc``                                                                         | 
+------------+-----------------------------------------------------------------------------------+
| external   | See their ``requirements.txt``                                                    | 
+------------+-----------------------------------------------------------------------------------+
Guillaume BINET's avatar
Guillaume BINET committed
129

Nick Groenen's avatar
Nick Groenen committed
130
**Configuration**
Guillaume BINET's avatar
Guillaume BINET committed
131

Nick Groenen's avatar
Nick Groenen committed
132 133 134
After installing Err, you must create a data directory somewhere on your system where
config and data may be stored. Find the installation directory of Err, then copy the
file <install_directory>/errbot/config-template.py to your data directory as config.py
135

Nick Groenen's avatar
Nick Groenen committed
136 137
(If you installed Err via pip, the installation directory will most likely be
/usr/lib64/python<python_version_number>/site-packages/errbot)
138

Nick Groenen's avatar
Nick Groenen committed
139
Read the documentation within this file and edit the values as needed so the bot can
140
connect to your chosen backend (XMPP, Hipchat, Slack ...) server.
141

Nick Groenen's avatar
Nick Groenen committed
142
**Starting the daemon**
143

Nick Groenen's avatar
Nick Groenen committed
144 145
The first time you start Err, it is recommended to run it in foreground mode. This can
be done with::
146

147
    <path_to_install_directory>/errbot/err.py
148

149 150
In many cases, just typing ``errbot`` will be enough as it is generally added to the ``$PATH``
automatically. Please pass -h or --help to ``errbot`` to get a list of supported parameters.
Nick Groenen's avatar
Nick Groenen committed
151 152
Depending on your situation, you may need to pass --config or --backend when starting
Err.
153

Nick Groenen's avatar
Nick Groenen committed
154 155
If all that worked, you can now use the -d (or --daemon) parameter to run it in a
detached mode::
156

157
    <path_to_install_directory>/errbot/err.py --daemon
158

Nick Groenen's avatar
Nick Groenen committed
159
**Hacking on Err's code directly**
Guillaume BINET's avatar
Guillaume BINET committed
160

Nick Groenen's avatar
Nick Groenen committed
161 162
It's important to know that as of version 2.0, Err is written for Python 3. In order
to run under Python 2.7 the code is run through 3to2 at install time. This means that
163
while it is possible to run Err under Python 3.3+ directly from a source checkout, it
Nick Groenen's avatar
Nick Groenen committed
164 165
is not possible to do so with Python 2.7. If you wish to develop or test with Err's
code under 2.7, you must run::
166

167
    python setup.py develop
168

169 170
Interacting with the Bot
------------------------
Guillaume BINET's avatar
Guillaume BINET committed
171

Nick Groenen's avatar
Nick Groenen committed
172 173 174
After starting Err, you should add the bot to your buddy list if you haven't already.
You can now send commands directly to the bot, or issue commands in a chatroom that
the bot has also joined.
Guillaume BINET's avatar
Guillaume BINET committed
175

Nick Groenen's avatar
Nick Groenen committed
176
To get a list of all available commands, you can issue::
177

Nick Groenen's avatar
Nick Groenen committed
178
    !help full
Guillaume BINET's avatar
Guillaume BINET committed
179

Nick Groenen's avatar
Nick Groenen committed
180
If you just wish to know more about a specific command you can issue::
181

Nick Groenen's avatar
Nick Groenen committed
182
    !help command
183

Nick Groenen's avatar
Nick Groenen committed
184
**Managing plugins**
185

Nick Groenen's avatar
Nick Groenen committed
186
To get a list of public plugin repos you can issue::
Guillaume BINET's avatar
Guillaume BINET committed
187

Nick Groenen's avatar
Nick Groenen committed
188 189 190 191 192
    !repos

To install a plugin from this list, issue::

    !repos install <name of plugin>
193 194

You can always uninstall a plugin again with::
Guillaume BINET's avatar
Guillaume BINET committed
195

Nick Groenen's avatar
Nick Groenen committed
196 197 198 199 200 201 202 203 204 205 206 207 208 209 210
    !repos uninstall <plugin>

You will probably want to update your plugins periodically. This can be done with::

    !repos update all

Note: Please pay attention when you install a plugin, it may have additional
dependencies. If the plugin contains a requirements.txt then Err wil automatically
check them and warn you when you are missing dependencies.

Writing plugins
---------------

Writing your own plugins is extremely simple. As an example, this is all it takes
to create a "Hello, world!" plugin for Err::
Guillaume BINET's avatar
Guillaume BINET committed
211

212 213
   from errbot import BotPlugin, botcmd
   
Nick Groenen's avatar
Nick Groenen committed
214 215
    class Hello(BotPlugin):
        """Example 'Hello, world!' plugin for Err"""
216
   
Nick Groenen's avatar
Nick Groenen committed
217 218 219 220
        @botcmd
        def hello(self, msg, args):
            """Return the phrase "Hello, world!" to you"""
            return "Hello, world!"
Guillaume BINET's avatar
Guillaume BINET committed
221

Nick Groenen's avatar
Nick Groenen committed
222
This plugin will create the command "!hello" which, when issued, returns "Hello, world!"
223 224
to you. For more info on everything you can do with plugins, see the
`plugin development guide <http://errbot.net/user_guide/plugin_development/>`_.