1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
Setup
=====
Prerequisites
-------------
Errbot runs under Python 3.6+ on Linux, Windows and Mac.
Installation
------------
Option 1: Use the package manager of your distribution (if available)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On some distributions, Errbot is also available as a package via your usual package manager.
In these cases, it is generally recommended to use your distribution's package instead of installing from PyPi but note
that the version packaged with your distribution may be a few versions behind.
Example of packaged versions of Errbot:
* Arch: https://aur.archlinux.org/packages/python-err/
* Docker: https://hub.docker.com/r/errbotio/errbot
* Gentoo: https://packages.gentoo.org/packages/net-im/err
Option 2: Installing Errbot in a virtualenv (preferred)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Installing into a `virtualenv`_ is **strongly** recommended.
If you have virtualenv installed, you can do for example::
virtualenv --python `which python3` ~/.errbot-ve
~/.errbot-ve/bin/pip install errbot
If you have virtualenvwrapper installed it is even simpler::
mkvirtualenv -p `which python3` errbot-ve
pip install errbot
Option 3: Installing Errbot at the system level (not recommended)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Errbot may be installed directly from PyPi using `pip`_ by issuing::
pip3 install errbot
.. note::
Some of errbot's dependencies need to build C extensions
which means you need to have development headers for some libraries installed.
On Debian/Ubuntu these may be installed with
`apt-get install python3-dev libssl-dev libffi-dev`
Package names may differ on other OS's.
.. _configuration:
First run
^^^^^^^^^
You can quickly configure Errbot by first creating a working directory and calling `errbot --init`::
mkdir ~/errbot-root
cd ~/errbot-root
errbot --init
This will create a minimally working errbot in text (development) mode. You can try it right away::
errbot
[...]
>>>
`>>>` is a prompt, you can talk to errbot directly. You can try::
!tryme
!help
!about
Configuration
-------------
Once you have installed errbot and did :code:`errbot --init`, you will have to tweak the generated `config.py` to connect
to your desired chat network.
You can use :download:`config-template.py` as a base for your `config.py`.
We'll go through the options that you absolutely must check now so that you can quickly get started
and make further tweaks to the configuration later on.
Open `config.py` in your favorite editor.
The first setting to check or change if `BOT_DATA_DIR` if correct.
This is the directory where the bot will store configuration data.
The first setting to check or change `BOT_LOG_FILE` to be sure it point to a writeable directory on your system.
The final configuration we absolutely must do is setting up a correct `BACKEND` which is set to `Text` by
:code:`errbot --init` but you can change to the name of the chat system you want to connect to (see the template above
for valid values).
You absolutely need a `BOT_IDENTITY` entry to set the credentials Errbot will use to connect to the chat system.
You can find here more details about configuring Errbot for some specific chat systems:
.. toctree::
:maxdepth: 1
Discord Backend (in readthedocs) <https://err-backend-discord.readthedocs.io/>
configuration/gitter
configuration/irc
configuration/mattermost
configuration/slackv3
configuration/telegram
configuration/xmpp
Starting the daemon
-------------------
The first time you start Errbot, it is recommended to run it in foreground mode. This can
be done with::
errbot
If you installed errbot into a virtualenv (as recommended),
call it by prefixing the virtualenv `bin/` directory::
/path/to/my/virtualenv/bin/errbot
Please pass -h or --help to errbot to get a list of supported parameters.
Depending on your situation,
you may need to pass --config (or -c)
pointing to the directory holding your `config.py`
when starting Errbot.
If all that worked out,
you can now use the -d (or --daemon) parameter to run it in a detached mode::
errbot --daemon
If you are going to run your bot all the time then using some process control system
such as `supervisor`_ is highly recommended. Installing and configuring such a system
is outside the scope of this document, however, we do provide some sample daemon configurations below.
.. note::
There are two ways to gracefully shut down a running bot.
You can use the :code:`!shutdown` command to do so via chat or you can send a `SIGINT` signal to the errbot process to do so from the commandline
If you're running errbot in the foreground then pressing Ctrl+C is equivalent to sending `SIGINT`.
Daemon Configurations
^^^^^^^^^^^^^^^^^^^^^
These are a few example configurations using common init daemons:
**supervisord** (`/etc/supervisor/conf.d/errbot.conf`)
.. literalinclude:: ../code_examples/supervisord.conf
:language: sh
**systemd** (`/etc/systemd/system/errbot.service`)
.. literalinclude:: ../code_examples/systemd.service
:language: sh
.. note::
Running errbot within a daemon process can have security implications if the daemon is started with an account containing elevated privileges.
We encourage errbot **not** be run under a `root` or `administrator` account but under a non-privileged account. The command below creates a non-privileged `errbot` account on Linux::
$ useradd --no-create-home --no-user-group -g nogroup -s /bin/false errbot
Upgrading
---------
Errbot comes bundled with a plugin which automatically performs a periodic update check.
Whenever there is a new release on PyPI,
this plugin will notify the users set in `BOT_ADMINS` about the new version.
Assuming you originally installed errbot using pip (see `installation`_),
you can upgrade errbot in much the same way.
If you used a virtualenv::
/path/to/my/virtualenv/bin/pip install --upgrade errbot
Or if you used pip without virtualenv::
pip install --upgrade errbot
It's recommended that you review the changelog before performing an upgrade
in case backwards-incompatible changes have been introduced in the new version.
The changelog for the release you will be installing can always be found
on `PyPI <https://pypi.org/project/errbot/>`_.
Provisioning (advanced)
-----------------------
See the :doc:`provisioning documentation </user_guide/provisioning>`
.. _virtualenv: https://virtualenv.pypa.io/en/latest/
.. _pip: https://pip.pypa.io/en/stable/
.. _supervisor: http://supervisord.org/
|
