2013-12-26

What is Hubot and why should I want it?

Hubot is an awesome chat bot open sourced by GitHub. It's easily extendable using CoffeeScript, and you can run it on pretty much every popular messaging service using a variety of adapters. Hubot is primarily a company chat bot that can be incredibly useful in daily operations - take a look at ChatOps at GitHub screencast to get the idea.

However, Hubot can be quite tricky configure and operate, and that's where Hubot Control comes in - it allows you to configure and manage multiple Hubot instances using a web interface.

This article will guide you through running Hubot on HipChat, but it is pretty similar to use any other adapter in same fashion, with exception of Skype, that requires you to jump some additional hoops.

Create a HipChat account for your Hubot

Add a new user from your existing HipChat account. Log in with this new user, enter desired chatrooms. Set your bot's @mention name to @hubot in account settings.

Prepare your system

We will be doing the setup on CentOS 6.4, but since there is nothing too CentOS specific in the steps, you can do the same using corresponding packages for your favorite Linux distribution.

For CentOS, you should have EPEL repo enabled to have access for all required packages.

Install system dependencies

You will need several things to get everything running. Let's make sure you have everything.

# Development libraries for compiling ruby and some gems 
$ yum install -y readline-devel zlib-devel libyaml-devel libffi-devel openssl-devel sqlite-devel

# Node and NPM
$ yum install npm --enablerepo=epel

# Required node packages
$ npm install -g coffee-script
$ npm install -g hubot
$ npm install -g hubot-hipchat

Prepare Hubot Control source

Hubot Control is a plain and simple Ruby on Rails webapp, there is no native packaging available, so we will clone the source code to our /opt directory:

$ cd /opt
$ git clone https://github.com/spajus/hubot-control.git

You may also want to use your own fork of Hubot Control.

Add hubot user

Running things as root is a very dangerous practice, so let's set up a fresh user just for Hubot, pointing it's home directory to /opt/hubot-control, where we just checked out our rails app:

$ useradd -d /opt/hubot-control hubot

Then make sure this new user has all the rights to /opt/hubot-control dir:

$ chown -R hubot:hubot /opt/hubot-control

Install RVM and Ruby 2.0.0

We will install RVM to get desired version of Ruby without messing up the system. As hubot, run:

$ su - hubot

# Will install RVM and Ruby 2.0.0. This will take a while.
$ \curl -sSL https://get.rvm.io | bash -s stable --ruby=2.0.0

# Will load RVM for the first time.
$ source ~/.rvm/scripts/rvm 

Afterwards ruby -v should show something like ruby 2.0.0p353 (2013-11-22 revision 43784) [x86_64-linux]/

Configure the database

You can configure Hubot Control to use any database you want - refer to Ruby on Rails configuration guide to do that. In this article we will be using SQLite in development mode, so it will work out of the box. However, to avoid installing PostgreSQL gem, which requires development libraries, we will remove gem 'pg' line from /opt/hubot-control/Gemfile, like so:

$ sed -i "/gem 'pg'/d" /opt/hubot-control/Gemfile

Install Ruby Gems

To be able to start Hubot Controll, you have to install the dependencies. We will do this as hubot user:

$ su - hubot
$ cd /opt/hubot-control
$ bundle install

What to do if some gem fails to install

If some gem will fail to install, you will most likely need to install a development library for a missing native ruby extension to compile properly. Then just try again. For example, if sqlite gem fails and sqlite-devel package is not installed, you will see this error:

An error occurred while installing sqlite3 (1.3.8), and Bundler cannot continue.
Make sure that `gem install sqlite3 -v '1.3.8'` succeeds before bundling.

To fix it, simply run as root:

$ yum install -y sqlite-devel

It should succeed this time, and then run bundle install again, to proceed with the rest of gem dependencies.

Prepare the database

A final step before starting Hubot Control for the first time is to create your database. If it's properly configured, this will succeed, and you will be good to go:

$ rake db:migrate

Run Hubot Control

Now it's time to run Hubot Control for the first time. We will do it in a straightforward way, by running:

$ cd /opt/hubot-control
$ rails server --port=3000

Rails will boot and you will see all the output right in your console. Now point your browser to http://your-server-ip:3000/status, login with [email protected] / hubot, and if you see a green heading saying You can run Hubot - you're almost there. If something is missing, you will see the cause along with instructions what to do.

When you will get everything running, you can start Hubot Control as a daemon using:

$ unicorn_rails -p <port> -D

Create a Hubot

To create a new Hubot, click Add Hubot and fill out the form. Set Title and Name to hubot, Adapter to hipchat and click Create. Now wait patiently for a while until you see a congratulatory screen with log output. You have just created a vanilla hubot instance. Click Control hubot button to proceed with further configuration.

Configure your Hubot

There are some final steps to take before your Hubot can connect to HipChat.

Variables

Click Configure button and go to Variables tab. This is where you have to add some configuration variables for the HipChat adapter. It should look something like this:

{
  "HUBOT_HIPCHAT_JID": "[email protected]",
  "HUBOT_HIPCHAT_PASSWORD": "MySuperSecretPassword",
}

Set the JID to the Jabber ID shown on your bot's XMPP/Jabber account settings.

package.json

In package.json tab you have to add hubot-hipchat dependency to dependencies block. You can find the exact version of the package in https://npmjs.org/package/hubot-hipchat.

{
  ...    
  "dependencies": {
    "hubot":         ">= 2.6.0 < 3.0.0",
    "hubot-scripts": ">= 2.5.0 < 3.0.0",
    "hubot-hipchat": ">= 2.6.4 < 3.0.0"
  },
  ...
}

Now hit Save all changes and you are ready to start.

Starting Hubot

Click hubot in the left sidebar and then click Start to start it. Be patient, since it's the first run, all dependencies will be installed, and Hubot Control will simply remain unresponsive. Go to your terminal where you started Hubot Control to check the output. When everything is installed, your Hubot should be running.

Testing Hubot on HipChat

Hubot will respond to @mention name - say @hubot ping in the chatroom and @hubot will respond with PONG. Say @hubot help to get the list of all commands.

You can extend this list by enabling third party scripts or writing your own using Hubot Control.

Hubot