gitter-bot-how-to

A tutorial on how to make a Gitter Bot

Summary

• Prerequisites
• First steps
• Configure your bot
• Publish
  • Host on Heroku
    • Prerequisites
    • Deployment Steps
  • Host on Azure
    • Prerequisites
    • Configuration Steps
    • Deployment Steps
    • Keep alive
• Ready to use
• Credits

Prerequisites

• A GitHub account to post to your Gitter rooms. While you could use your own account, this may be confusing to your users, so a new, separate account may be better
• Once you have created your new GitHub account, log into the Gitter Developer Page, and then access this page and take a note of the accounts Personal Access Token
• You are going to need a cloud infrastructure somewhere to host your hubot instance. For example, you can host on Heroku or on Azure, or on your own
• Have node.js installed (which includes npm)

First steps

To get hubot, these are the steps that should be followed.

NOTE: Although there are two hubot adapter's for Gitter, we found that only one of them works reliably. Namely, this one. The other one seems older, and has been replaced by the one that we ended up using.

1. Login into Gitter with the GitHub account that you are going to use as your bot
2. Join the room(s) that you want the bot to be activated on

Configure your bot

You can follow the installation process from hubot-gitter2 here.

Or you can follow these steps :

1. npm install -g hubot coffee-script yo generator-hubot
2. mkdir -p <yourbotname> where <yourbotname> is the name of your bot
3. yo hubot (when prompted, enter gitter2 as adapter name, and <yourbotname> as name
4. npm install --save hubot-gitter2
5. Create git repository (git init, git add ., git commit -m "Initial commit")

NOTE: Ideally, you would then want to push the repository that you just created to "somewhere" for storage, perhaps GitHub or BitBucket.

You can then test your bot with the following command line where <your token> is the token provided by Gitter.

HUBOT_GITTER2_TOKEN=<your token> ./bin/hubot -a gitter2

Publish

Host on Heroku

Prerequisites

• You will need a Heroku account in order to continue
• Install Heroku Toolbelt

Deployment Steps

NOTE: The steps regarding Keep alive, sleep and wake up are ONLY required if you are running on a Hobby Heroku instance. If you are using a paid for plan, then you can ignore these steps. When running on a Hobby Plan, the Heroku Dyno is only allowed to run for 18 hours a day. This keepalive routine allows the bot to continue running without any interaction, and still remain within the rules of the free account.

1. Navigate to the directory where you created your bot above

2. heroku login

3. heroku create

4. heroku config:set HUBOT_GITTER2_TOKEN=**** (here the token is the Personal Access Token for Github Account that will be running as the bot.

5. heroku config:set HEROKU_URL=https://<URL> (this is to keep the heroku application alive. The URL is generated from the heroku create command above

6. heroku config:set HUBOT_ADAPTER="gitter2" (this ensures we use the gitter2 adapter)

7. heroku config:set HUBOT_HEROKU_KEEPALIVE_INTERVAL=5 (this is the interval that the heroku instance will be polled to keep it active. Value is in minutes)

8. heroku config:set HUBOT_HEROKU_KEEPALIVE_URL=https://<URL>/ (this is URL that will be pinged each keep alive attempt. Should be the same as the URL above. Notice the trailing slash, which is very important!)

9. heroku config:set HUBOT_HEROKU_SLEEP_TIME=22:00 (this is UTC time at which the hubot instance will go to sleep. 22:00 is the default, but you can change this to whatever suits you.)

10. heroku config:set HUBOT_HEROKU_WAKEUP_TIME=06:00 (this it the UTC time at which the hubot instance will wake up. 06:00 is the default, but you can change this to whatever suits you.)

11. heroku addons:create scheduler:standard (this adds the free heroku scheduler to your account)

12. Sign into your heroku account, and click on the newly created scheduler

13. Edit the settings of the job to look like the following: NOTE: The next due time you be set as the same as the HUBOT_HEROKU_WAKEUP_TIME above.

14. git push heroku master

15. heroku logs (if all goes well here, you should see something simalar to the following)

Host on Azure

Prerequisites

• You will need an Azure account in order to continue.
• Install Azure Command Line Interface - npm install -g azure-cli

Configuration Steps

HOTFIX: Due to the fact that there has been a fix on the develop branch of the hubot-gitter2 repository to make it work on Azure, you will need to make the following adjustment to the package.json file. Change this line :

"hubot-gitter2": "git://github.com/huafu/hubot-gitter2.git#develop",

Once a new release of the hubot-gitter2 is available, you will not need to do this change. You can subscribe to this issue to know when a new release is available.

1. azure site deploymentscript --node
2. Edit external-scripts.json file and remove these lines
   • "hubot-heroku-keepalive",
   • "hubot-redis-brain,
3. Create a new file server.js in the root directory that contains these 2 lines
   • require('coffee-script/register');
module.exports = require('bin/hubot.coffee');
4. npm install coffee-script --save
5. Open deploy.cmd and add a new line under Deployment section (after the 3rd step)
   • :: 4. Create Hubot file with a coffee extension
copy /Y "%DEPLOYMENT_TARGET%\bin\hubot" "%DEPLOYMENT_TARGET%\bin\hubot.coffee"
6. Commit this change on your repo (git commit -m "Add Azure deployment configuration")
7. Publish your code to your favorite source control (see below in Steps.3)

Deployment Steps

1. Login into Azure dashboard
2. Create a new App Services with the name, for example <yourbotname>
3. Under the Publishing settings, click on Continuous deployment section and then choose the source of your code among these options :
   • Visual Studio Team Services
   • OneDrive
   • Local Git Repository
   • GitHub
   • Bitbucket
   • Dropbox
   • An external repository
4. Under the General settings, click on Application settings and fill with key/value pairs
   • add gitter token (key: HUBOT_GITTER2_TOKEN, value: <your token>)
   • add hubot adapter (key: HUBOT_ADAPTER, value: gitter2)
   • add hubot name (key: HUBOT_NAME, value: <yourbotname>)

Keep alive

If you use the free version of Azure websites, you could be suprised that your bot stop to after around 20 minutes. That's because the application pool sleep after a period of inactivity. To keep your service awake, you can use the service uptimerobot.com.

1. Sign-up or login to the service
2. Add new monitor
3. Configure your monitor like this
   • Monitor type : Ping
   • Friendly Name : <yourbotname>
   • IP (or host) : http://<yourbotname>.azurewebsites.net/<yourbotname>/help
   • Monitoring interval : every 15 minutes

Ready to use

If all of the above has worked, go to your Gitter Chat Room, and try issuing a hubot command like hubot ping and hopefully you will see the following:

Credits

• Thanks to CultureOps for his blog post Running Hubot in an Azure website ?