mirror of https://github.com/zulip/zulip.git
docs: Split bots guide into running and writing guides.
This commit is contained in:
derAnfaenger
Tim Abbott
parent
eef72a98e4
commit
6b879a2b04
|
|
@ -81,6 +81,8 @@ Contents:
|
|||
integration-guide
|
||||
integration-docs-guide
|
||||
webhook-walkthrough
|
||||
running-bots-guide
|
||||
writing-bots-guide
|
||||
new-feature-tutorial
|
||||
writing-views
|
||||
life-of-a-request
|
||||
|
|
@ -132,7 +134,6 @@ Contents:
|
|||
settings
|
||||
events-system
|
||||
queuing
|
||||
bots-guide
|
||||
custom-apps
|
||||
pointer
|
||||
markdown
|
||||
|
|
|
|||
|
|
@ -0,0 +1,217 @@
|
|||
# Running bots in Zulip
|
||||
|
||||
Zulip's features can be extended by the means of bots and integrations.
|
||||
|
||||
* **Integrations** are used to connect Zulip with different chat, scheduling and workflow software.
|
||||
If this is what you are looking for, please check out the [integrations guide](
|
||||
http://zulip.readthedocs.io/en/latest/integration-guide.html?highlight=integrations).
|
||||
* **Bots**, as a more general concept, intercept and react to messages.
|
||||
If this is what you are looking for, read on!
|
||||
|
||||
The purpose of this documentation is to provide you with information about Zulip's
|
||||
bot system.
|
||||
|
||||
On this page you'll find:
|
||||
|
||||
* A step-by-step [tutorial](#how-to-run-a-bot) on how to run a bot.
|
||||
* Common [problems](#common-problems) when developing/running bots and their solutions.
|
||||
|
||||
Contributions to this guide are very welcome, so if you run into any
|
||||
issues following these instructions or come up with any tips or tools
|
||||
that help with writing bots, please visit
|
||||
[#integrations](https://chat.zulip.org/#narrow/stream/integrations) on the
|
||||
[Zulip development community server](https://chat.zulip.org), open an
|
||||
issue, or submit a pull request to share your ideas!
|
||||
|
||||
## Installing the `zulip_bots` package
|
||||
|
||||
The `zulip_bots` package comes with all you need to run a bot.
|
||||
|
||||
### Installing a stable version
|
||||
|
||||
Run `pip install zulip_bots`.
|
||||
|
||||
## How to run a bot
|
||||
|
||||
This guide will show you how to run a bot on a running Zulip
|
||||
server. It assumes you want to use one of the existing `zulip_bots/bots`
|
||||
bots in your Zulip organization.
|
||||
|
||||
*Looking for an easy way to test a bot's output? Check out [this](
|
||||
#testing-a-bot-s-output) section.*
|
||||
|
||||
You need:
|
||||
|
||||
* An account in an organization on a Zulip server
|
||||
(e.g. [chat.zulip.org](https://chat.zulip.org) or
|
||||
yourSubdomain.zulipchat.com, or your own development server).
|
||||
Within that Zulip organization, users will be able to interact with
|
||||
your bot.
|
||||
* A computer where you're running the bot from.
|
||||
|
||||
**Note: Please be considerate when testing experimental bots on
|
||||
public servers such as chat.zulip.org.**
|
||||
|
||||
1. [Install all requirements](#installing-the-zulip-bots-package).
|
||||
|
||||
2. Register a new bot user on the Zulip server's web interface.
|
||||
|
||||
* Log in to the Zulip server.
|
||||
* Navigate to *Settings (<i class="fa fa-cog"></i>)* -> *Your bots* -> *Add a new bot*.
|
||||
Select *Generic bot* for bot type, fill out the form and click on *Create bot*.
|
||||
* A new bot user should appear in the *Active bots* panel.
|
||||
|
||||
3. Download the bot's `.zuliprc` configuration file to your computer.
|
||||
|
||||
* In the *Active bots* panel, click on the little green download icon
|
||||
to download its configuration file *.zuliprc* (the structure of this file is
|
||||
explained [here](#configuration-file)).
|
||||
* Copy the file to a destination of your choice, e.g. to `~/.zuliprc`.
|
||||
|
||||
4. Run the bot.
|
||||
|
||||
* Run
|
||||
```
|
||||
zulip-run-bot <bot-name> --config-file ~/.zuliprc
|
||||
```
|
||||
(using the path to the `.zuliprc` file from step 3).
|
||||
* Check the output of the command. It should start with the text
|
||||
the `usage` function returns, followed by logging output similar
|
||||
to this:
|
||||
|
||||
```
|
||||
INFO:root:starting message handling...
|
||||
INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): localhost
|
||||
```
|
||||
|
||||
* Congrats! Now, your bot should be ready to test.
|
||||
|
||||
### Testing the helloworld bot
|
||||
|
||||
* The `helloworld` bot is a simple bot that responds with a 'beep boop'
|
||||
when queried. It can be used as a template to build more complex
|
||||
bots.
|
||||
* In a stream and topic of your choice, type `@<your bot name>`.
|
||||
The `helloworld` bot should respond with "beep boop".
|
||||
|
||||
## Zulip Botserver
|
||||
|
||||
The Zulip Botserver is for people who want to
|
||||
|
||||
* run bots in production.
|
||||
* run multiple bots at once.
|
||||
|
||||
The Zulip Botserver is a Python (Flask) server that implements Zulip's
|
||||
Outgoing Webhooks API. You can of course write your own servers using
|
||||
the Outgoing Webhooks API, but the Botserver is designed to make it
|
||||
easy for a novice Python programmer to write a new bot and deploy it
|
||||
in production.
|
||||
|
||||
### Installing the Zulip Botserver
|
||||
|
||||
Install the `zulip_botserver` PyPI package using `pip`:
|
||||
```
|
||||
pip install zulip_botserver
|
||||
```
|
||||
|
||||
### Running bots using the Zulip Botserver
|
||||
|
||||
1. Register new bot users on the Zulip server's web interface.
|
||||
|
||||
* Log in to the Zulip server.
|
||||
* Navigate to *Settings (<i class="fa fa-cog"></i>)* -> *Your bots* -> *Add a new bot*.
|
||||
Select *Outgoing webhook* for bot type, fill out the form and click on *Create bot*.
|
||||
* A new bot user should appear in the *Active bots* panel.
|
||||
|
||||
2. Download the `flaskbotrc` from the `your-bots` settings page. It
|
||||
contains the configuration details for all the active outgoing
|
||||
webhook bots. It's structure is very similar to that of .zuliprc.
|
||||
|
||||
3. Run the Zulip Botserver by passing the `flaskbotrc` to it. The
|
||||
command format is:
|
||||
|
||||
```
|
||||
zulip-bot-server --config-file <path_to_flaskbotrc> --hostname <address> --port <port>
|
||||
```
|
||||
|
||||
If omitted, `hostname` defaults to `127.0.0.1` and `port` to `5002`.
|
||||
|
||||
4. Now set up the outgoing webhook service which will interact with
|
||||
the server: Create an **Outgoing webhook** bot with its base url
|
||||
of the form:
|
||||
|
||||
```
|
||||
http://<hostname>:<port>/bots/<bot_name>
|
||||
```
|
||||
|
||||
`bot_name` refers to the name in the email address you specified
|
||||
for the bot. It can be obtained by removing `-bot@*.*` from the
|
||||
bot email: For example, the bot name of a bot with an email
|
||||
`followup-bot@zulip.com` is `followup`.
|
||||
|
||||
In the development environment, an outgoing webhook bot and
|
||||
corresponding service already exist, with the email
|
||||
`outgoing-webhook@zulip.com`. This can be used for interacting
|
||||
with flask server bots.
|
||||
|
||||
5. Congrats, everything is set up! Test your botserver like you would
|
||||
test a normal bot.
|
||||
|
||||
### Running Zulip Botserver with `supervisord`
|
||||
|
||||
[supervisord](http://supervisord.org/) is a popular tool for running
|
||||
services in production. It helps ensure the service starts on boot,
|
||||
manages log files, restarts the service if it crashes, etc. This
|
||||
section documents how to run the Zulip Botserver using *supervisord*.
|
||||
|
||||
Running the Zulip Botserver with *supervisord* works almost like
|
||||
running it manually.
|
||||
|
||||
0. Install *supervisord* via your package manager; e.g. on Debian/Ubuntu:
|
||||
```
|
||||
sudo apt-get install supervisor
|
||||
```
|
||||
|
||||
1. Configure *supervisord*. *supervisord* stores its configuration in
|
||||
`/etc/supervisor/conf.d`.
|
||||
* Do **one** of the following:
|
||||
* Download the [sample config file](
|
||||
https://raw.githubusercontent.com/zulip/python-zulip-api/master/zulip_botserver/zulip-botserver-supervisord.conf)
|
||||
and store it in `/etc/supervisor/conf.d/zulip-botserver.conf`.
|
||||
* Copy the following section into your existing supervisord config file.
|
||||
```
|
||||
[program:zulip-bot-server]
|
||||
command=zulip-bot-server --config-file=<path/to/your/flaskbotrc> --hostname <address> --port <port>
|
||||
startsecs=3
|
||||
stdout_logfile=/var/log/zulip-botserver.log ; all output of your botserver will be logged here
|
||||
redirect_stderr=true
|
||||
```
|
||||
* Edit the `<>` sections according to your preferences.
|
||||
|
||||
2. Update *supervisord* to read the configuration file:
|
||||
```
|
||||
supervisorctl reread
|
||||
supervisorctl update
|
||||
```
|
||||
(or you can use `/etc/init.d/supervisord restart`, but this is less
|
||||
disruptive if you're using *supervisord* for other services as well).
|
||||
|
||||
3. Test if your setup is successful:
|
||||
```
|
||||
supervisorctl status
|
||||
```
|
||||
The output should include a line similar to this:
|
||||
> zulip-bot-server RUNNING pid 28154, uptime 0:00:27
|
||||
|
||||
The standard output of the bot server will be logged to the path in
|
||||
your *supervisord* configuration.
|
||||
|
||||
## Common problems
|
||||
|
||||
* My bot won't start
|
||||
* Ensure that your API config file is correct (download the config file from the server).
|
||||
* Ensure that you bot script is located in zulip_bots/bots/<my-bot>/
|
||||
* Are you using your own Zulip development server? Ensure that you run your bot outside
|
||||
the Vagrant environment.
|
||||
* Some bots require Python 3. Try switching to a Python 3 environment before running
|
||||
your bot.
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Zulip bot system
|
||||
# Writing bots in Zulip
|
||||
|
||||
Zulip's features can be extended by the means of bots and integrations.
|
||||
|
||||
|
|
@ -13,7 +13,6 @@ bot system.
|
|||
|
||||
On this page you'll find:
|
||||
|
||||
* A step-by-step [tutorial](#how-to-run-a-bot) on how to run a bot.
|
||||
* A step-by-step [tutorial](#how-to-develop-a-bot) on how to develop a bot.
|
||||
* A [documentation](#bot-api) of the bot API.
|
||||
* Common [problems](#common-problems) when developing/running bots and their solutions.
|
||||
|
|
@ -61,15 +60,7 @@ zulip_bots
|
|||
Each subdirectory in `bots` contains a bot. When developing bots, try to use the structure outlined
|
||||
above as an orientation.
|
||||
|
||||
## Installing the `zulip_bots` package
|
||||
|
||||
The `zulip_bots` package comes with all you need to run a bot.
|
||||
|
||||
### Installing a stable version
|
||||
|
||||
Run `pip install zulip_bots`.
|
||||
|
||||
### Installing a development version
|
||||
## Installing a development version of the `zulip_bots` package
|
||||
|
||||
1. `git clone https://github.com/zulip/python-zulip-api.git` - clone the [python-zulip-api](
|
||||
https://github.com/zulip/python-zulip-api) repository.
|
||||
|
|
@ -85,76 +76,12 @@ Run `pip install zulip_bots`.
|
|||
*Hint: `./tools/provision` installs `zulip`, `zulip_bots`, and `zulip_botserver` in developer
|
||||
mode. This enables you to make changes to the code after the packages are installed.*
|
||||
|
||||
## How to run a bot
|
||||
|
||||
This guide will show you how to run a bot on a running Zulip
|
||||
server. It assumes you want to use one of the existing `zulip_bots/bots`
|
||||
bots in your Zulip organization. If you want to write a new one, you
|
||||
just need to write the `<my-bot>.py` script and put it into `zulip_bots/bots/<my-bot>` directory.
|
||||
|
||||
*Looking for an easy way to test a bot's output? Check out [this](
|
||||
#testing-a-bot-s-output) section.*
|
||||
|
||||
You need:
|
||||
|
||||
* An account in an organization on a Zulip server
|
||||
(e.g. [chat.zulip.org](https://chat.zulip.org) or
|
||||
yourSubdomain.zulipchat.com, or your own development server).
|
||||
Within that Zulip organization, users will be able to interact with
|
||||
your bot.
|
||||
* A computer where you're running the bot from.
|
||||
|
||||
**Note: Please be considerate when testing experimental bots on
|
||||
public servers such as chat.zulip.org.**
|
||||
|
||||
1. [Install all requirements](#installing-the-zulip-bots-package).
|
||||
|
||||
2. Register a new bot user on the Zulip server's web interface.
|
||||
|
||||
* Log in to the Zulip server.
|
||||
* Navigate to *Settings (<i class="fa fa-cog"></i>)* -> *Your bots* -> *Add a new bot*.
|
||||
Select *Generic bot* for bot type, fill out the form and click on *Create bot*.
|
||||
* A new bot user should appear in the *Active bots* panel.
|
||||
|
||||
3. Download the bot's `.zuliprc` configuration file to your computer.
|
||||
|
||||
* In the *Active bots* panel, click on the little green download icon
|
||||
to download its configuration file *.zuliprc* (the structure of this file is
|
||||
explained [here](#configuration-file)).
|
||||
* Copy the file to a destination of your choice, e.g. to `~/.zuliprc`.
|
||||
|
||||
4. Run the bot.
|
||||
|
||||
* Run
|
||||
```
|
||||
zulip-run-bot <bot-name> --config-file ~/.zuliprc
|
||||
```
|
||||
(using the path to the `.zuliprc` file from step 3).
|
||||
* Check the output of the command. It should start with the text
|
||||
the `usage` function returns, followed by logging output similar
|
||||
to this:
|
||||
|
||||
```
|
||||
INFO:root:starting message handling...
|
||||
INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): localhost
|
||||
```
|
||||
|
||||
* Congrats! Now, your bot should be ready to test.
|
||||
|
||||
### Testing the helloworld bot
|
||||
|
||||
* The `helloworld` bot is a simple bot that responds with a 'beep boop'
|
||||
when queried. It can be used as a template to build more complex
|
||||
bots.
|
||||
* In a stream and topic of your choice, type `@<your bot name>`.
|
||||
The `helloworld` bot should respond with "beep boop".
|
||||
|
||||
### Testing a bot's output
|
||||
|
||||
If you just want to see how a bot reacts to a message, but don't want to set it up on a server,
|
||||
we have a little tool to help you out: `zulip-bot-output`
|
||||
|
||||
* [Install all requirements](#installing-the-zulip-bots-package).
|
||||
* [Install all requirements](#installing-a-development-version-of-the-zulip-bots-package).
|
||||
|
||||
* Run `zulip-bot-output <bot-name> --message "<your-message>"` to test one of the bots in
|
||||
[`zulip_bots/bots`](https://github.com/zulip/python-zulip-api/tree/master/zulip_bots/zulip_bots/bots)
|
||||
|
|
@ -169,118 +96,6 @@ we have a little tool to help you out: `zulip-bot-output`
|
|||
|
||||
Response: `12.0 meter = 13.12336 yard`
|
||||
|
||||
## Zulip Botserver
|
||||
|
||||
The Zulip Botserver is for people who want to
|
||||
|
||||
* run bots in production.
|
||||
* run multiple bots at once.
|
||||
|
||||
The Zulip Botserver is a Python (Flask) server that implements Zulip's
|
||||
Outgoing Webhooks API. You can of course write your own servers using
|
||||
the Outgoing Webhooks API, but the Botserver is designed to make it
|
||||
easy for a novice Python programmer to write a new bot and deploy it
|
||||
in production.
|
||||
|
||||
### Installing the Zulip Botserver
|
||||
|
||||
Install the `zulip_botserver` PyPI package using `pip`:
|
||||
```
|
||||
pip install zulip_botserver
|
||||
```
|
||||
|
||||
### Running bots using the Zulip Botserver
|
||||
|
||||
1. Register new bot users on the Zulip server's web interface.
|
||||
|
||||
* Log in to the Zulip server.
|
||||
* Navigate to *Settings (<i class="fa fa-cog"></i>)* -> *Your bots* -> *Add a new bot*.
|
||||
Select *Outgoing webhook* for bot type, fill out the form and click on *Create bot*.
|
||||
* A new bot user should appear in the *Active bots* panel.
|
||||
|
||||
2. Download the `flaskbotrc` from the `your-bots` settings page. It
|
||||
contains the configuration details for all the active outgoing
|
||||
webhook bots. It's structure is very similar to that of .zuliprc.
|
||||
|
||||
3. Run the Zulip Botserver by passing the `flaskbotrc` to it. The
|
||||
command format is:
|
||||
|
||||
```
|
||||
zulip-bot-server --config-file <path_to_flaskbotrc> --hostname <address> --port <port>
|
||||
```
|
||||
|
||||
If omitted, `hostname` defaults to `127.0.0.1` and `port` to `5002`.
|
||||
|
||||
4. Now set up the outgoing webhook service which will interact with
|
||||
the server: Create an **Outgoing webhook** bot with its base url
|
||||
of the form:
|
||||
|
||||
```
|
||||
http://<hostname>:<port>/bots/<bot_name>
|
||||
```
|
||||
|
||||
`bot_name` refers to the name in the email address you specified
|
||||
for the bot. It can be obtained by removing `-bot@*.*` from the
|
||||
bot email: For example, the bot name of a bot with an email
|
||||
`followup-bot@zulip.com` is `followup`.
|
||||
|
||||
In the development environment, an outgoing webhook bot and
|
||||
corresponding service already exist, with the email
|
||||
`outgoing-webhook@zulip.com`. This can be used for interacting
|
||||
with flask server bots.
|
||||
|
||||
5. Congrats, everything is set up! Test your botserver like you would
|
||||
test a normal bot.
|
||||
|
||||
### Running Zulip Botserver with `supervisord`
|
||||
|
||||
[supervisord](http://supervisord.org/) is a popular tool for running
|
||||
services in production. It helps ensure the service starts on boot,
|
||||
manages log files, restarts the service if it crashes, etc. This
|
||||
section documents how to run the Zulip Botserver using *supervisord*.
|
||||
|
||||
Running the Zulip Botserver with *supervisord* works almost like
|
||||
running it manually.
|
||||
|
||||
0. Install *supervisord* via your package manager; e.g. on Debian/Ubuntu:
|
||||
```
|
||||
sudo apt-get install supervisor
|
||||
```
|
||||
|
||||
1. Configure *supervisord*. *supervisord* stores its configuration in
|
||||
`/etc/supervisor/conf.d`.
|
||||
* Do **one** of the following:
|
||||
* Download the [sample config file](
|
||||
https://raw.githubusercontent.com/zulip/python-zulip-api/master/zulip_botserver/zulip-botserver-supervisord.conf)
|
||||
and store it in `/etc/supervisor/conf.d/zulip-botserver.conf`.
|
||||
* Copy the following section into your existing supervisord config file.
|
||||
```
|
||||
[program:zulip-bot-server]
|
||||
command=zulip-bot-server --config-file=<path/to/your/flaskbotrc> --hostname <address> --port <port>
|
||||
startsecs=3
|
||||
stdout_logfile=/var/log/zulip-botserver.log ; all output of your botserver will be logged here
|
||||
redirect_stderr=true
|
||||
```
|
||||
* Edit the `<>` sections according to your preferences.
|
||||
|
||||
2. Update *supervisord* to read the configuration file:
|
||||
```
|
||||
supervisorctl reread
|
||||
supervisorctl update
|
||||
```
|
||||
(or you can use `/etc/init.d/supervisord restart`, but this is less
|
||||
disruptive if you're using *supervisord* for other services as well).
|
||||
|
||||
3. Test if your setup is successful:
|
||||
```
|
||||
supervisorctl status
|
||||
```
|
||||
The output should include a line similar to this:
|
||||
> zulip-bot-server RUNNING pid 28154, uptime 0:00:27
|
||||
|
||||
The standard output of the bot server will be logged to the path in
|
||||
your *supervisord* configuration.
|
||||
|
||||
## How to develop a bot
|
||||
|
||||
The tutorial below explains the structure of a bot `<my-bot>.py`,
|
||||
|
|
@ -519,7 +519,7 @@ def build_custom_checkers(by_lang):
|
|||
color = next(colors)
|
||||
markdown_docs_length_exclude = {
|
||||
"api/bots/converter/readme.md",
|
||||
"docs/bots-guide.md",
|
||||
"docs/running-bots-guide.md",
|
||||
"docs/dev-env-first-time-contributors.md",
|
||||
"docs/webhook-walkthrough.md",
|
||||
"docs/life-of-a-request.md",
|
||||
|
|
|
|||
Loading…
Reference in New Issue