Installation

In the instructions below, your copy of zulipbot will be referred to as @zulipbot.

Getting started

Before you get started, make sure you have installed and configured Git on your local machine.

Installation

1. Open your command line interface (CLI).

2. Download the latest release or clone this repository to your local machine.

$ git clone https://github.com/zulip/zulipbot.git

3. Switch to the local copy of this repository.

$ cd ~/path-to-repo/zulipbot

4. Install the necessary node packages and dependencies. Any npm WARN warnings can be safely ignored.

$ npm install

Configuration

1. Create two files in the src folder: one file named config.js, the other named secrets.js.

$ touch src/config.js
$ touch src/secrets.js

2. Open src/config.js in your preferred text editor.

3. Edit the contents of src/config.js, using src/zulip_project.config.js as a guide; visit the Configuration page for more details.

4. Once you are finished modifying src/config.js, run tools/configLint to check if your configuration file was set up properly.

$ tools/configLint

5. Open src/secrets.js in your preferred text editor.

6. Edit the contents of src/secrets.js as follows:

module.exports = {
  username: "Username123", // Username123 is the username of the GitHub user account that @zulipbot will use
  password: "Password456" // Password456 is the password of the GitHub user account that @zulipbot will use
};

7. Run the bot to ensure that your environment was configured correctly.

$ npm start

Connecting to GitHub

In order to receive events from GitHub, @zulipbot must be running on a server. We recommend using Heroku or Amazon Web Services (AWS) for hosting your copy of @zulipbot, since both services offer free plans to their consumers. You can choose to host your copy of @zulipbot locally, but it is highly discouraged.

Additionally, if you haven't done so already, you need to create a GitHub account for @zulipbot to use; the username and password of the account should be exactly the same as the ones that you specified in src/secrets.js.

1. Invite @zulipbot to collaborate on your repository.
2. Change @zulipbot's permission level in the repository to Admin.
3. Add a webhook to your repository:
   • Enter your server's URL in the Payload URL field.
   • Set the Content type field to application/json.
   • Select the "Send me everything." option in the Which events would you like to trigger this webhook? field.

If the web hook's payload was sent successfully, you have successfully installed and set up @zulipbot on your server! Congratulations! You can now begin using @zulipbot on your repository.