Bot Butler

The Bot Butler is a collection of scripts for Hubot that have been built and tested against Symphony, using the Hubot Symphony adapter.

Scripts can be tested locally or deployed as a Docker container; additional scripts can be easily defined and distributed.

Local run

1. git clone https://github.com/symphonyoss/bot-butler.git ; cd bot-butler - Checkout the bot-butler project
2. cp env.sh.sample env.sh - Configure environment variables (more on configuration below)
3. Install NodeJS 4.0 or higher
4. npm install - Install all project dependencies (in ./node_modules folder)
5. npm run generate-hubot - Generate the hubot butler bot in ./butler-build folder; if the ./butler-build already exists, it won't be overridden
6. npm run start-bot-butler - Run it

To clean the generated bot simply type npm run clean; to know more about npm run scripts, checkout package.json.

Please note that, between steps 5 and 6, you can edit the ./butler-build contents, change dependency versions, add more hubot scripts dependencies and more; alternatively, you can edit bootstrap/build.sh to add any configuration step after the yo command.

Docker run

1. Checkout project and set environment variables (as above, steps 1 and 2)
2. Create the Docker image - docker build -t butler:v0.9.0 .
3. Run the Docker image - docker run butler:v0.9.0

The root folder of the project will be mounted on /home/butler; as such, the following folder will be inherited by default:

• src/scripts into /home/butler/butler-build/scripts
• ./env.sh into /home/butler/butler-build/env.sh
• ./certs into /home/butler/butler-build/certs

To override default values, use the following syntax:

docker run -v /myscripts:/home/butler/scripts -v /mycerts:/home/butler/certs butler:v0.9.0

To check the Docker image contents, without launching the bot, run:

docker run -it --entrypoint /bin/bash butler:v0.9.0

Configuration

Bot configurations are defined by environment variables in env.sh file, located in the root folder of the project; since the file may contain sensitive information, it is ignored by github; a env.sh.sample file is provided to copy from.

Below are the configuration items:

• Symphony Pod coordinates: the Symphony API endpoint coordinates; make sure they point to the Symphony Pod you want to use and that you have access to it; default values are pointing to the Foundation Open Developer Platform:

export HUBOT_SYMPHONY_HOST=foundation-dev.symphony.com
export HUBOT_SYMPHONY_KM_HOST=foundation-dev-api.symphony.com
export HUBOT_SYMPHONY_SESSIONAUTH_HOST=foundation-dev-api.symphony.com
export HUBOT_SYMPHONY_AGENT_HOST=foundation-dev-api.symphony.com

Read more on hubot-symphony.

• Bot Certificates: Ensure that you load your Bot user certificate and PrivateKey into the ./certs folder

export HUBOT_SYMPHONY_PUBLIC_KEY=./certs/bot-PublicCert.pem
export HUBOT_SYMPHONY_PRIVATE_KEY=./certs/bot-PrivateKey.pem
export HUBOT_SYMPHONY_PASSPHRASE=changeit

If you want to know more about how to generate and register a certificate for your Symphony pod, checkout the Foundation certificate-toolbox; bear in mind that:

1. HUBOT_SYMPHONY_PUBLIC_KEY must point to user/<bot-name>-cert.pem
2. HUBOT_SYMPHONY_PRIVATE_KEY must point to user/<bot-name>-key.pem
3. user/<bot-name>-key.pem have no password; set it using openssl rsa-in ./user/<bot-name>-key.pem -out ./user/<bot-name>.key.pem -des3

Each script defined in src/scripts) may need some environment variables to be configured, for example:

export HUBOT_JIRA_URL=https://symphonyoss.atlassian.net
export HUBOT_JIRA_USERNAME=username
export HUBOT_JIRA_PASSWORD=password

Proxy configuration

If your Hubot instance will be behind a Proxy, you will need to follow these instructions prior to a local or Docker run.

1. Edit bootstrap/start.sh and add - at the beginning of the file - the following statements, which configure NodeJS to use a Proxy server for outbound connections:

export http_proxy=http://proxy.company.com:8080
export https_proxy=http://proxy.company.com:8080

2. Create src/scripts/_proxy.coffee (underscore is intentional in the naming so the script is loading first!) to forward all HTTP requests:

proxy = require 'proxy-agent'
module.exports = (robot) ->
 robot.globalHttpOptions.httpAgent =
proxy('http://proxy.company.com:8080', true)
 robot.globalHttpOptions.httpsAgent =
proxy('http://proxy.company.com:8080', true)

Customise scripts

Writing a custom script

Want to write your own Hubot script? The best way is to take a look at an existing script and follow the hubot-scripts documentation.

All custom Hubot scripts in src/scripts are included in the bot; to define a sub-set of them, you can define a hubot-scripts.json file, which is created by npm run generate-hubot command and is empty by default.

Any third-party dependencies for scripts need the addition of your package.json otherwise a lot of errors will be thrown during the start up of your hubot. You can find a list of dependencies for a script in the documentation header at the top of the script.

Distributing a custom script

Hubot scripts can be automatically referenced if:

• listed in the hubot-scripts organization page
• tagged on npmjs as hubot-scripts

The easiest way is to publish the npm package using hubot-scripts as tag; read more on https://www.npmjs.org/browse/keyword/hubot-scripts

Project dependencies

Bot Butler scripts depend on the following components:

• Hubot
• Hubot Symphony adapter
• Yeoman
• Generator Hubot

The build.sh script invokes Yeoman, which generates a node project from scratch, using the generator-hubot; as such, the package.json dependencies definition doesn't impact the final bot runtime and it's only used to report on dependency metadata, such as security vulnerabilities and license compliance.

The Versioneye dashboard reads the yarn.lock file committed in the root project folder; to update it:

1. Install Yarn
2. run yarn install --force
3. Push any change to yarn.lock