docs: Add a page on deploying bots in production.

This commit is contained in:
Tim Abbott 2018-05-18 16:12:18 -07:00
parent 0ba5c9c07d
commit dd7507c88a
3 changed files with 129 additions and 109 deletions

View File

@ -0,0 +1,128 @@
# Deploying bots in production
Usually, work on a bot starts on a laptop. At some point, you'll want
to deploy your bot in a production environment, so that it'll stay up
regardless of what's happening with your laptop. There are several
options for doing so:
* The simplest is running `zulip-run-bot` inside a `screen` session on
a server. This works, but if your server reboots, you'll need to
manually restart it, so we don't recommend it.
* Using `supervisord` or a similar tool for managing a production
process with `zulip-run-bot`. This consumes a bit of resources
(since you need a persistent process running), but otherwise works
great.
* Using the Zulip Botserver, which is a simple Flask server for
running a bot in production, and connecting that to Zulip's outgoing
webhooks feature. This can be deployed in environments like
Heroko's free tier without running a persistent process.
## 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. Construct the URL for your bot, which will be of the form:
```
http://<hostname>:<port>/bots/<bot_name>
```
where the `hostname` is the hostname you'll be running the bot
server on, and `port` is the port for it (the recommended default
is `5002`). `bot_name` is the name of the Python module for the
bot you'd like to run.
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 (using
the URL from above) and click on *Create bot*.
* A new bot user should appear in the *Active bots* panel.
1. 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.
1. 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`.
1. 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.
1. 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][supervisord-config-file]
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.
[supervisord-config-file]: https://raw.githubusercontent.com/zulip/python-zulip-api/master/zulip_botserver/zulip-botserver-supervisord.conf
1. 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).
1. 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.

View File

@ -74,115 +74,6 @@ like. Eventually, you'll probably want to run it in a production
environment where it'll stay up, by deploying it on a server using the
Zulip Botserver.
## 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. Construct the URL for your bot, which will be of the form:
```
http://<hostname>:<port>/bots/<bot_name>
```
where the `hostname` is the hostname you'll be running the bot
server on, and `port` is the port for it (the recommended default
is `5002`). `bot_name` is the name of the Python module for the
bot you'd like to run.
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 (using
the URL from above) and click on *Create bot*.
* A new bot user should appear in the *Active bots* panel.
1. 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.
1. 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`.
1. 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.
1. 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][supervisord-config-file]
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.
[supervisord-config-file]: https://raw.githubusercontent.com/zulip/python-zulip-api/master/zulip_botserver/zulip-botserver-supervisord.conf
1. 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).
1. 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

View File

@ -12,6 +12,7 @@
## Interactive bots (beta)
* [Running bots](/api/running-bots)
* [Deploying bots](/api/deploying-bots)
* [Writing bots](/api/writing-bots)
## REST API