mirror of https://github.com/zulip/zulip.git
docs: Add a page on deploying bots in production.
This commit is contained in:
parent
0ba5c9c07d
commit
dd7507c88a
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
|
@ -12,6 +12,7 @@
|
|||
## Interactive bots (beta)
|
||||
|
||||
* [Running bots](/api/running-bots)
|
||||
* [Deploying bots](/api/deploying-bots)
|
||||
* [Writing bots](/api/writing-bots)
|
||||
|
||||
## REST API
|
||||
|
|
Loading…
Reference in New Issue