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

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

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

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

13
.. image:: https://img.shields.io/badge/License-GPLv3-green.svg
14
   :target: https://pypi.python.org/pypi/errbot
Guillaume Binet's avatar
Guillaume Binet committed
15
   :alt: License
Guillaume Binet's avatar
Guillaume Binet committed
16

17
.. image:: https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg
Guillaume Binet's avatar
Guillaume Binet committed
18
   :target: https://gitter.im/errbotio/errbot?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
Guillaume Binet's avatar
Guillaume Binet committed
19
   :alt: Join the chat at https://gitter.im/errbotio/errbot
20

21 22 23
|
|

Guillaume Binet's avatar
Guillaume Binet committed
24
.. image:: http://errbot.io/_static/err.png
Guillaume Binet's avatar
Guillaume Binet committed
25
   :target: http://errbot.io
26

Guillaume Binet's avatar
Guillaume Binet committed
27

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

31
Errbot 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
Errbot 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

Guillaume Binet's avatar
Guillaume Binet committed
45 46 47 48 49 50 51 52
- `Slack support <https://slack.com/>`_ (built-in)
- `Hipchat support <http://www.hipchat.org/>`_ (built-in)
- `Telegram support <https://www.telegram.org/>`_ (built-in)
- `XMPP support <http://xmpp.org>`_ (built-in support)
- IRC support (built-in)
- `Gitter support <https://gitter.im/>`_ (Follow `gitter instructions <https://github.com/errbotio/err-backend-gitter>`_ to install it)
- `CampFire <https://campfirenow.com/>`_ (Follow `campfire instructions <https://github.com/errbotio/err-backend-campfire>`_ to install it)
- `TOX <https://tox.im/>`_ (Follow the `tox instructions from <https://github.com/errbotio/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
- 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.
63
- logs: can be inspected from chat or streamed to 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
---------------------

Guillaume Binet's avatar
Guillaume Binet committed
80
If you have a question or want to share your latest plugin creation: feel free to join the chat on `gitter team chat <https://gitter.im/errbotio/errbot>`_. Errbot 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
But if you have a bug to report or wish to request a feature, please log them `here <https://github.com/errbotio/errbot/issues>`_.
82 83

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

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

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

91
Errbot 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
If you can, we recommend to setup a `virtualenv <https://pypi.python.org/pypi/virtualenv>`_.

98
Errbot 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

104
    pip install https://github.com/errbotio/errbot/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 Errbot.
Nick Groenen's avatar
Nick Groenen committed
110
Depending on the backend you choose, additional requirements need to be installed.
111

Guillaume Binet's avatar
Guillaume Binet committed
112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
+------------+------------------------------------+
| Backend    | Extra dependencies                 |
+============+====================================+
| Slack      | - ``slackclient``                  |
+------------+------------------------------------+
| XMPP       | - ``sleekxmpp``                    |
|            | - ``pyasn1``                       |
|            | - ``pyasn1-modules``               |
|            | - ``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

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

136
(If you installed Errbot via pip, the installation directory will most likely be
Nick Groenen's avatar
Nick Groenen committed
137
/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

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

147
    errbot
148

149
In many cases, just using ``errbot`` will be enough as it is generally added to the ``$PATH``
150
automatically. Please pass -h or --help to ``errbot`` to get a list of supported parameters.
Nick Groenen's avatar
Nick Groenen committed
151
Depending on your situation, you may need to pass --config or --backend when starting
152
Errbot.
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
    errbot --daemon
158

159
**Hacking on Errbot's code directly**
Guillaume BINET's avatar
Guillaume BINET committed
160

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

167
    python setup.py develop
168

169 170 171 172
If you want to test your bot instance without havign to connect to a chat service, you can run it in text modeqith ::

   errbot -T
   
Guillaume Binet's avatar
Guillaume Binet committed
173
Or in graphical mode (you'll need to install the dependency pyside for that)::
174 175 176

   errbot -G

177 178
Interacting with the Bot
------------------------
Guillaume BINET's avatar
Guillaume BINET committed
179

180
After starting Errbot, you should add the bot to your buddy list if you haven't already.
Nick Groenen's avatar
Nick Groenen committed
181 182
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
183

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

Nick Groenen's avatar
Nick Groenen committed
186
    !help full
Guillaume BINET's avatar
Guillaume BINET committed
187

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

Nick Groenen's avatar
Nick Groenen committed
190
    !help command
191

Nick Groenen's avatar
Nick Groenen committed
192
**Managing plugins**
193

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

Nick Groenen's avatar
Nick Groenen committed
196 197 198 199 200
    !repos

To install a plugin from this list, issue::

    !repos install <name of plugin>
201 202

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

Nick Groenen's avatar
Nick Groenen committed
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
211
dependencies. If the plugin contains a requirements.txt then Errbot will automatically
Nick Groenen's avatar
Nick Groenen committed
212 213 214 215 216 217
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
218
to create a "Hello, world!" plugin for Errbot::
Guillaume BINET's avatar
Guillaume BINET committed
219

220 221
   from errbot import BotPlugin, botcmd
   
Nick Groenen's avatar
Nick Groenen committed
222
    class Hello(BotPlugin):
223
        """Example 'Hello, world!' plugin for Errbot"""
224
   
Nick Groenen's avatar
Nick Groenen committed
225 226 227 228
        @botcmd
        def hello(self, msg, args):
            """Return the phrase "Hello, world!" to you"""
            return "Hello, world!"
Guillaume BINET's avatar
Guillaume BINET committed
229

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