diff --git a/templates/zerver/api/deploying-bots.md b/templates/zerver/api/deploying-bots.md new file mode 100644 index 0000000000..6deb8ca35f --- /dev/null +++ b/templates/zerver/api/deploying-bots.md @@ -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://:/bots/ + ``` + + 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 ()* -> *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 --hostname
--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= + --hostname
--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. + diff --git a/templates/zerver/api/running-bots.md b/templates/zerver/api/running-bots.md index 1974f6be18..59bb5bc3ca 100644 --- a/templates/zerver/api/running-bots.md +++ b/templates/zerver/api/running-bots.md @@ -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://:/bots/ - ``` - - 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 ()* -> *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 --hostname
--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= - --hostname
--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 diff --git a/templates/zerver/api/sidebar.md b/templates/zerver/api/sidebar.md index d9c8313bb7..8af2d6a10b 100644 --- a/templates/zerver/api/sidebar.md +++ b/templates/zerver/api/sidebar.md @@ -12,6 +12,7 @@ ## Interactive bots (beta) * [Running bots](/api/running-bots) +* [Deploying bots](/api/deploying-bots) * [Writing bots](/api/writing-bots) ## REST API