Hubot from Github is a great tool for both fun and automation. We trialled it along side our HipChat trial by installing it onto a free Heroku instance. To give us more flexibility when we went live we moved it to a Digital Ocean droplet along side our testing environments. Here’s how it went.
Preparation
Hubot is a Node.js application, so we need to prep the server to enable it to run, obviously by installing Node.js
Tools
First off, its usually a good idea to ensure you have the latest versions of everything
yum -y update
As we’re going to be building the latest Node.js from source (the one in the yum repos is a bit old) we will need various build tools. The easiest way to get these installed is via a group install.
yum -y groupinstall 'Development tools'
Installing Node.js
Now we have everything in place we’re good to install Node.js. I usually keep my software sources in /usr/local/src/ so lets move into that directory now
cd /usr/local/src
Next we need to fetch the latest version of Node.js from the website at http://nodejs.org/download. Right click on the Source Code and save the link location. At the time of writing this was
http://nodejs.org/dist/v0.10.23/node-v0.10.23.tar.gz
Now lets get this tar ball onto the server
wget http://nodejs.org/dist/v0.10.23/node-v0.10.23.tar.gz
Once the download is complete we need to unpack the file and switch into the directory that is created
tar -xzf node-v0.10.23.tar.gz
cd node-v0.10.23
The last three commands are familiar to anyone who has installed something from source before. The first prepares the compiler for the environment, the second compiles the source code and the last one installs Node.js system wide.
./configure
make
make install
You run each one by itself and let it complete fully, watching for any errors. If you have followed this section you shouldn’t have had any issues and will now have Node.js installed on your server. Happily in the later versions of Node.js the npm package manager is shipped so there is no longer a need to install that separately, which is nice as we’ll need that next.
CoffeeScript
If you haven’t come across CoffeeScript, in brief it is a great language that compiles down into Javascript. It has polarised developers who either love or hate it. Personally I’m in the former camp and always look for ways to work it into projects.
From coffeescript.org
CoffeeScript is a little language that compiles into JavaScript. Underneath that awkward Java-esque patina, JavaScript has always had a gorgeous heart. CoffeeScript is an attempt to expose the good parts of JavaScript in a simple way.
Hubot is written in CoffeeScript and you will need to write any custom plugins using it. Therefore it’s the next thing we need to install.
npm install -g coffee-script
The -g switch in the command installs this as a global library for Node.js rather than a local one.
Redis
From their website redis.io.
Redis is an open source, BSD licensed, advanced key-value store.
We are going to use Redis for Hubot’s brain, by which I mean persistent storage. I’m not going to cover using it in this guide, but Hubot will complain if it can’t find redid-server.
My droplet is a Centos 6.4 box, so I used the REMI repository to make it easy. Depending on the distro you are using you may have to find a guide, but there are plenty out on the internet as redis is a popular storage tool
1 Get the require yum repositories
rpm -Uvh http://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm
rpm -Uvh http://rpms.famillecollet.com/enterprise/remi-release-6.rpm
2 Install
yum install redis -y
3 Start the server and ensure it starts on boot
service redis start
chkconfig redis on
At this point the server is prepped and ready to be used for our new Hubot install.
Install Hubot
Having done all our preparation the final step is relatively easy. First off we’re going to install hubot as a global Node.js module
npm install -g hubot
Then pick where you want your new bot to reside. I’ve used my home directory for this guide. Move into that location and create a new hubot and install it.
cd
hubot --create hubot
cd hubot
npm install
The final command above installs the bot with its dependencies and the standard package of scripts that you can use with hubot.
Once this has completed, run the following command to check everything is working
./bin/hubot
Your new bot should start up and you can have a chat with it.
Hubot> hubot ping
Hubot> PONG
Hubot> hubot image me success
Hubot> http://www.drsunil.com/wp/wp-content/uploads/2013/06/success-on-mountain-top-shutterstock_115642099.jpg#.png
Hubot>
Note: Your image url will be different from the one here as Hubot will fetch something random for you
Keeping your Hubot running
Assuming you have done all over the above via an SSH tunnel, you may well be thinking how to keep your new bot running when you close the session down. Well there are many different ways you can do this, I’m going to offer two here.
nohup
The nohup command (or no-hangup) can prefix any command on the SSH session and it will leave it running when the session ends. In this example you would simply start your Hubot with
nohup ./bin/hubot
and then close the terminal tab/window to leave the service running. While this is certainly easy, it feels messy to me so I personally prefer…
tumx
tmux is a “terminal multiplexer” and it is awesome. I use it every day as part of my general workflow (and will be writing about it in a separate post eventually), but for now I’ll simply say that it is perfect for this situation
Installing it is just another yum command away
yum install -y tmux
Start a new tmux session with the following command, which also names the session for easy reference later
tmux new -s hubot
At this point you will be running on a terminal in the multiplexer, rather than a normal one. There is practically no difference, but what you can do is simply run the command to start hubot normally, then exit this tmux session. Assuming no custom tmux configurations it would be the following
cd /path/to/hubot
./bin/hubot
<Ctrl-b>-D
If that last bit looks strange, well basically you hold the control key down and press b, release both and press d
The control-d tells tmux your next command is for it no the shell, then the d detaches the tmux session and leaves hubot running in the background.
And that’s it. For now anyway. You may want to investigate other ways to keep hubot running, and you may want to look at tools that will restart it if it fails for any reason. Automation is key here, and the Readme on the hubot Github repo has some information about that, just follow the link to Installing on Unix
Now that Hubot is installed and running, what to do with it. Well, integrating with a chat service allows you to chat with your bot and get it to run tasks and add a little fun to your group. At work we started using HipChat, so I’m going to cover how I integrated our hosted Hubot with HipChat.
HipChat
HipChat is a group chat, IM and file sharing tool for teams. Adding Hubot to it increases the functionality drastically. From the social/fun side of bombarding colleges with pictures of pugs, to enabling a deployment pipeline that is accessible to the whole team, not just those with server access.
Dependencies
Getting Hubot to access HipChat isn’t too hard, but first we need a couple of dependencies on the server.
yum install -y libicu-devel compat-expat
Next we’re going to stop our Hubot and make some changes to its source. Now if you used the tmux suggestion in the previous section then you need to get back into your session
tmux a -t hubot
This command reattaches your current SSH session to the tmux session named hubot. You should now see the running bot, hit control-c to shut it down.
Now we need to install the HipChat adapter for hubot, which can be done via Node.js. This assumes you are in the hubot directory.
npm install --save hubot-hipchat
Now, in order for hubot to connect to HipChat, it needs a HipChat user. So off to the admin panel and create a user. The first thing you need to do after creating the bots user on HipChat is to login and look at the XMPP/Jabber page for the accounts Jabber ID which will look something like 1234_56789@chat.hipchat.com. Make a note, you’ll need this in a minute.
Right, back in the terminal, we’re going to create a new start up script for Hubot which handles connecting to HipChat.
In the hubot dir create a new file called run.sh and add the following to it
#!/bin/bash
export HUBOT_HIPCHAT_JID=""
export HUBOT_HIPCHAT_PASSWORD=""
bin/hubot --adapter hipchat
Put the Jabber ID we noted earlier into the first environment variable and the password for the HipChat account into the second then save the file.
Lastly, make the new start up script executable with chmod
chmod +x run.sh
Now to start hubot use ./run.sh instead of the ./bin/hubot. This sets up the environment variables and starts hubot using the HipChat adapter.
If everything is working you should see the following:
[Wed Dec 18 2013 21:20:53 GMT+0000 (UTC)] INFO Connecting HipChat adapter...
[Wed Dec 18 2013 21:20:55 GMT+0000 (UTC)] INFO Connected to hipchat.com as @Hubot
[Wed Dec 18 2013 21:20:55 GMT+0000 (UTC)] INFO Data for brain retrieved from Redis
[Wed Dec 18 2013 21:20:56 GMT+0000 (UTC)] INFO Joining 12345_room@conf.hipchat.com
Your bot should now be logged into your HipChat channel and will respond to @Hubot requests within group chats or hubot requests in 1-to-1 chats.
Note: The @name will depend on the user account you set up in HipChat, and the HipChat adapter will take care of the rest