Skip to content

Commit

Permalink
update formatting and line breaks
Browse files Browse the repository at this point in the history
  • Loading branch information
@tombell
tombell committed Jun 20, 2013
1 parent 60199aa commit 308b01c
Show file tree
Hide file tree
Showing 5 changed files with 122 additions and 64 deletions.
26 changes: 19 additions & 7 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,29 +2,38 @@

## Getting Started With Hubot

You will need [node.js](nodejs.org/) and [npm](https://npmjs.org/). Joyent has an [excellent blog post on how to those installed](http://joyent.com/blog/installing-node-and-npm), so we'll omit detailing that here for right now.
You will need [node.js](nodejs.org/) and [npm](https://npmjs.org/). Joyent has
an [excellent blog post on how to those installed](http://joyent.com/blog/installing-node-and-npm), so we'll omit detailing that here for right now.

Once node and npm are ready, we can install hubot and coffeescript:

% npm install -g hubot coffeescript

This will give us the `hubot` script, which is used for running a hubot, but more importantly to start, generating your own hubot. The name of the new bot is the last argument, and will be created in the directory of the same name. For example, to create a new bot named myhubot:
This will give us the `hubot` script, which is used for running a hubot, but
more importantly to start, generating your own hubot. The name of the new bot is
the last argument, and will be created in the directory of the same name. For
example, to create a new bot named myhubot:

% hubot --create myhubot

If you are using git, the generated bot includes a .gitignore, so you can initialize and add everything:
If you are using git, the generated bot includes a .gitignore, so you can
initialize and add everything:

% cd bender
% git init
% git add .
% git commit -m "Initial commit"

You have have your own runnable instance of hubot! There's a `bin/hubot` command for convenience, to handle installing npm dependencies, loading scripts, and then launching your hubot.
You have have your own runnable instance of hubot! There's a `bin/hubot`
command for convenience, to handle installing npm dependencies, loading scripts,
and then launching your hubot.

% bin/hubot
Hubot>

This has loaded hubot using the [shell adapter](docs/adapters/shell.md), which is very useful for development. Note the `Hubot>` though. This is the name he'll `respond` to with commands. For example, to list available commands:
This has loaded hubot using the [shell adapter](docs/adapters/shell.md), which
is very useful for development. Note the `Hubot>` though. This is the name he'll
`respond` to with commands. For example, to list available commands:

% bin/hubot
Hubot> hubot: help
Expand Down Expand Up @@ -56,12 +65,15 @@ This has loaded hubot using the [shell adapter](docs/adapters/shell.md), which i
pug me - Receive a pug
ship it - Display a motivation squirrel

You almost definitely will want to change his name. bin/hubot takes a `--name` option towards this end:
You almost definitely will want to change his name. bin/hubot takes a `--name`
option towards this end:

% bin/hubot --name myhubot
myhubot>

Now your hubot will respond to `myhobot`. It's worth noting that this is case-insensitive, and that you can prefix with `@` or suffix with `:`. That means these are equivalent:
Now your hubot will respond to `myhobot`. It's worth noting that this is
case-insensitive, and that you can prefix with `@` or suffix with `:`. That
means these are equivalent:

MYHUBOT help
myhubot help
Expand Down
8 changes: 5 additions & 3 deletions docs/adapters.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@ Hubot includes two official adapters:

## Third Party Adapters

Third party adapters are available as `npm` packages. Here is a list of known adapters, but please [submit an issue](https://github.com/github/hubot/issues) to have yours added to the list:
Third party adapters are available as `npm` packages. Here is a list of known
adapters, but please [submit an issue](https://github.com/github/hubot/issues)
to have yours added to the list:

* [Flowdock](https://github.com/flowdock/hubot-flowdock)
* [HipChat](https://github.com/hipchat/hubot-hipchat)
Expand All @@ -32,5 +34,5 @@ Third party adapters are available as `npm` packages. Here is a list of known ad
## Writing Your Own adapter

The best place to start is `src/adapter.coffee`, and inheriting from `Adapter`.
There is not as much documentation as could exist (yet!), so it is worth reviewing
existing adapters as well as how hubot internally uses an adapter.
There is not as much documentation as could exist (yet!), so it is worth
reviewing existing adapters as well as how hubot internally uses an adapter.
18 changes: 10 additions & 8 deletions docs/adapters/campfire.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
# Adapter: Campfire

[Campfire](http://campfirenow.com/) is a web based chat application built by [37signals](http://37signals.com). The Campfire
adapter is one of the original adapters in Hubot.
[Campfire](http://campfirenow.com/) is a web based chat application built by
[37signals](http://37signals.com). The Campfire adapter is one of the original
adapters in Hubot.

## Getting Started

You will need a Campfire account to to start, which you can [sign up for
free](https://signup.37signals.com/campfire/free/signup/new).
You will need a Campfire account to to start, which you can
[sign up for free](https://signup.37signals.com/campfire/free/signup/new).

Next, you will need to create a user on your Campfire account for your Hubot, then
give it access so it can join to your rooms. You will need to create a room if you haven't
already.
Next, you will need to create a user on your Campfire account for your Hubot,
then give it access so it can join to your rooms. You will need to create a room
if you haven't already.

Hubot defaults to using its [shell](shell.md), so to use Campfire instead, you can run hubot with `-a campfire`:
Hubot defaults to using its [shell](shell.md), so to use Campfire instead, you
can run hubot with `-a campfire`:

% bin/hubot -a campfire

Expand Down
81 changes: 48 additions & 33 deletions docs/deploying/heroku.md
View file
Original file line number Diff line number Diff line change
@@ -1,52 +1,67 @@
# Deploying Hubot to Heroku

Once you have [gotten started](../deploying.md) with Hubot, it's time to deploy so you can use it outside of your local machine. [Heroku](http://www.heroku.com/) is an easy and supported way to deploy hubot.
Once you have [gotten started](../deploying.md) with Hubot, it's time to deploy
so you can use it outside of your local machine.
[Heroku](http://www.heroku.com/) is an easy and supported way to deploy hubot.

To start, install the [Heroku Toolbelt](https://toolbelt.heroku.com/) if you haven't already. Follow their `Getting Started' instructions, including logging in:
To start, install the [Heroku Toolbelt](https://toolbelt.heroku.com/) if you
haven't already. Follow their `Getting Started' instructions, including logging
in:

```
% heroku login
Enter your Heroku credentials.
Email: [email protected]
Password:
Could not find an existing public key.
Would you like to generate one? [Yn]
Generating new SSH public key.
Uploading ssh public key /Users/technicalpickles/.ssh/id_rsa.pub
```
% heroku login
Enter your Heroku credentials.
Email: [email protected]
Password:
Could not find an existing public key.
Would you like to generate one? [Yn]
Generating new SSH public key.
Uploading ssh public key /Users/technicalpickles/.ssh/id_rsa.pub

Inside your new hubot instance, you'll need to create a Heroku application for it. Make sure it is a git repository first and commit anything you've done so far, then you can create the app:
Inside your new hubot instance, you'll need to create a Heroku application for
it. Make sure it is a git repository first and commit anything you've done so
far, then you can create the app:

```
% heroku create
Creating stark-fog-398... done, stack is cedar
http://stark-fog-398.herokuapp.com/ | [email protected]:stark-fog-398.git
Git remote heroku added
```
% heroku create
Creating stark-fog-398... done, stack is cedar
http://stark-fog-398.herokuapp.com/ | [email protected]:stark-fog-398.git
Git remote heroku added

Before you deploy the application, you'll need to configure some environment variables for hubot to use. The variables you need depends on which [adapter](../adapters.md) and scripts you are using. For Campfire, with no other scripts, you'd need to at least:
Before you deploy the application, you'll need to configure some environment
variables for hubot to use. The variables you need depends on which
[adapter](../adapters.md) and scripts you are using. For Campfire, with no other
scripts, you'd need to at least:

```
% heroku config:add HUBOT_CAMPFIRE_ACCOUNT=yourcampfireaccount
% heroku config:add HUBOT_CAMPFIRE_TOKEN=yourcampfiretoken
% heroku config:add HUBOT_CAMPFIRE_ROOMS=comma,separated,list,of,rooms,to,join
```
% heroku config:add HUBOT_CAMPFIRE_ACCOUNT=yourcampfireaccount
% heroku config:add HUBOT_CAMPFIRE_TOKEN=yourcampfiretoken
% heroku config:add HUBOT_CAMPFIRE_ROOMS=comma,separated,list,of,rooms,to,join

In addition is one special environment variable for Heroku. The default hubot [Procfile](https://devcenter.heroku.com/articles/procfile) marks the process as a 'web' process type, in order to support serving up http requests (more on that in the [scripting docs](../scripting.md). The downside of this is that dynos will [idle after an hour of inactivity](https://devcenter.heroku.com/articles/dynos#dyno-idling). That means your hubot would leave after an hour, assuming you don't hit the web interface, and only rejoin when it does get traffic. This is extremely inconvenient, since most interaction is done through chat. To mitigate this, there's a special environment variable to make hubot regularly ping itself. If the app is deployed to http://stark-fog-398.herokuapp.com/, then you'd configure:
In addition is one special environment variable for Heroku. The default hubot
[Procfile](https://devcenter.heroku.com/articles/procfile) marks the process as
a 'web' process type, in order to support serving up http requests (more on that
in the [scripting docs](../scripting.md). The downside of this is that dynos
will [idle after an hour of inactivity](https://devcenter.heroku.com/articles/dynos#dyno-idling).
That means your hubot would leave after an hour, assuming you don't hit the web
interface, and only rejoin when it does get traffic. This is extremely
inconvenient, since most interaction is done through chat. To mitigate this,
there's a special environment variable to make hubot regularly ping itself. If
the app is deployed to http://stark-fog-398.herokuapp.com/, then you'd
configure:

% heroku config:add HUBOT_HEROKU_URL=http://stark-fog-398.herokuapp.com

At this point, you are ready to deploy and start chatting. With Heroku, that's a git push away:
At this point, you are ready to deploy and start chatting. With Heroku, that's a
git push away:

% git push heroku master

You'll see some text flying, and eventually some success. You should be able to see your bot in your configured chat rooms at this point. If not, you can peek at the logs to try to debug:
You'll see some text flying, and eventually some success. You should be able to
see your bot in your configured chat rooms at this point. If not, you can peek
at the logs to try to debug:

% heroku logs

If you make any changes to your hubot, just commit them, and push them as before:
If you make any changes to your hubot, just commit them, and push them as
before:

```
% git ci -a -m "Awesome scripts OMG"
% git push heroku master
```
% git ci -a -m "Awesome scripts OMG"
% git push heroku master
53 changes: 40 additions & 13 deletions docs/deploying/unix.md
View file
Original file line number Diff line number Diff line change
@@ -1,39 +1,66 @@
# Deploying Hubot to UNIX

Because there are so many variations of Linux, and more generally UNIX, it's difficult for the hubot team to have canonical documentation for installing and deploying it to every version out there. So, this is an attempt to give an overview of what's needed to get deploying.
Because there are so many variations of Linux, and more generally UNIX, it's
difficult for the hubot team to have canonical documentation for installing and
deploying it to every version out there. So, this is an attempt to give an
overview of what's needed to get deploying.

There's 3 primary things to deploying and running hubot:

* node and npm
* a way to get source code updated on the server
* a way to start hubot, start it up if it crashes, and restart it when code updates
* node and npm
* a way to get source code updated on the server
* a way to start hubot, start it up if it crashes, and restart it when code
updates

## node and npm

To start, your UNIX server will need node and npm. Check out the node.js wiki for [installing Node.js via package manager](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager), [Building on GNU/Linux and other UNIX](https://github.com/joyent/node/wiki/Installation#building-on-gnulinux-and-other-unix).
To start, your UNIX server will need node and npm. Check out the node.js wiki
for [installing Node.js via package manager](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager), [Building on GNU/Linux and other UNIX](https://github.com/joyent/node/wiki/Installation#building-on-gnulinux-and-other-unix).

## Updating code on the server

The simplest way to update your hubot's code is going to be to have a git checkout of your hubot's source code, and just git pull to get change. This may feel a dirty hack, but it works when you are starting out.
The simplest way to update your hubot's code is going to be to have a git
checkout of your hubot's source code, and just git pull to get change. This may
feel a dirty hack, but it works when you are starting out.

If you have a Ruby background, you might be more comfortable using [capistrano](https://github.com/capistrano/capistrano).
If you have a Ruby background, you might be more comfortable using
[capistrano](https://github.com/capistrano/capistrano).

If you have a [Chef](http://www.opscode.com/chef/) background, there's a [deploy](http://docs.opscode.com/resource_deploy.html) resource for managing deployments.
If you have a [Chef](http://www.opscode.com/chef/) background, there's a
[deploy](http://docs.opscode.com/resource_deploy.html) resource for managing
deployments.

## Starting, stopping, and restarting hubot

Every hubot install has a `bin/hubot` script to handle starting up the hubot. You can just run this command from your git checkout on the server, but there's problems:
Every hubot install has a `bin/hubot` script to handle starting up the hubot.
You can just run this command from your git checkout on the server, but there's
problems:

* you disconnect, and hubot dies
* hubot dies, for any reason, and doesn't start again
* it doesn't start up at boot automatically

For handling you disconnecting, you can start with running `bin/hubot` in [screen session](http://www.gnu.org/software/screen/) or with [nohup](http://linux.die.net/man/1/nohup).
For handling you disconnecting, you can start with running `bin/hubot` in
[screen session](http://www.gnu.org/software/screen/) or with
[nohup](http://linux.die.net/man/1/nohup).

For handling hubot dying, and restarting it automatically, you can imagine running `bin/hubot` in a [bash while loop](http://tldp.org/HOWTO/Bash-Prog-Intro-HOWTO-7.html#ss7.3). But really, you probably want some process monitoring using tools like [monit](http://mmonit.com/monit/), [god](http://godrb.com/), [bluepill](https://github.com/arya/bluepill), [upstart](http://upstart.ubuntu.com/).
For handling hubot dying, and restarting it automatically, you can imagine
running `bin/hubot` in a
[bash while loop](http://tldp.org/HOWTO/Bash-Prog-Intro-HOWTO-7.html#ss7.3). But
really, you probably want some process monitoring using tools like
[monit](http://mmonit.com/monit/),
[god](http://godrb.com/),
[bluepill](https://github.com/arya/bluepill),
[upstart](http://upstart.ubuntu.com/).

For starting at boot, you can create an init script for appropriate your UNIX distribution, or if you are using one the process monitoring tools above, make sure it boots at startup.
For starting at boot, you can create an init script for appropriate your UNIX
distribution, or if you are using one the process monitoring tools above, make
sure it boots at startup.

## Recommendations

This document has been deliberately light on strong recommendations. At a high level though, it's strongly recommended to avoid anything that is overly manual and non-repeatable. That would mean using your OS's packages and tools whenever possible, and having a proper deploy tool to update hubot, and process management to keep hubot running.
This document has been deliberately light on strong recommendations. At a high
level though, it's strongly recommended to avoid anything that is overly manual
and non-repeatable. That would mean using your OS's packages and tools whenever
possible, and having a proper deploy tool to update hubot, and process
management to keep hubot running.

0 comments on commit 308b01c

Please sign in to comment.