Testing Instructions

1. Fetch the source code.

First, fetch the latest python-zulip-api repo.

git clone https://github.com/zulip/python-zulip-api

Second, clone the server repo.

git clone https://github.com/aero31aero/zulip-botmatrix

Third, install docker and set it up such that your primary non-root user account can access it. Use this account to start the botmatrix server.

2. Setup the server

Follow the instructions here: https://github.com/aero31aero/zulip-botmatrix/blob/master/README.md

Before step 5, create a new github oauth app and store it's details in the two environment variables: github_client_id and github_client_secret.

Now, you can start the server by running tools/run.

3. Getting Deployment Key

Go to http://localhost:5000 and login using GitHub, followed by copying the API key there, and closing the page. Apologies for the crude interface. I'm pretty sure there are some bugs in there as well, and I'll be refining it as we go on.

4. Environment Setup

On your local terminal,

export TOKEN="your-copied-key-here"
export SERVER="http://localhost:5000"

5. Deployment

cd into python-zulip-api and follow the below steps.

Now, for deployment, first we need to prepare a bot. That involves installing its dependencies and making its docker image and this process can take some time. Sample command for preparing the bot:

tools/deploy prepare my-bot-name \
  --path zulip_bots/zulip_bots/bots/helloworld \
  --config ~/Downloads/zuliprc \
  --main helloworld.py

This command, if successful, should give an output akin to:

pack: Created zip file at: .bots/hello.zip.
upload: Uploaded the bot package to botfarm.
clean: Removed .bots/hello.zip.
process: The bot has been processed by the botfarm.

6. Starting and stopping the bot

Use the bot name you just specified above for these commands:

tools/deploy start my-bot-name
tools/deploy stop my-bot-name

7. More Stuff

Run tools/deploy --help to print the complete help text. More commands available are ls, delete, log.

PM me/message on https://chat.zulip.org/#narrow/stream/127-integrations/topic/botfarm regarding testing and any bugs you find.

Notes:

The main server's repo name is bot-matrix as of now, and would be finalized before it is moved from my account over to the zulip github org.
The UI is definitely not good in the main server, and it is practically just a working proof of concept as of now. If you need any help setting it up, do tell.
Known issue: weird bug if you prepare a bot, start it, then upload another bot with the same name and start it as well. The older container keeps running but is not listed because its image has been wiped. This is being fixed.
In the latest PR #P381, the usage has been made simpler by automatically picking up the token and serrver url from environment variables.

References:

aero31aero/tools-deploy.md