Expose Ruby applications to the web via ReverseHTTP
Ruby
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
lib Ignore comm_inactivity_timeout to prevent event machine problems (bac… Apr 10, 2010
samples
.gitignore
README.rdoc
Rakefile
VERSION.yml
hookout.gemspec

README.rdoc

Hookout - Reverse HTTP Webhooks

Developing webhook based applications from behind a firewall or NAT provides many challenges. The biggest is allowing external applications to see your hook. Hookout allows you to use a ReverseHTTP (www.reversehttp.net) server to expose your application to the outside world, without needing to configure any complicated firewall holes.

Getting Started

Installing

Hookout can be installed via RubyGems with:

gem sources -a http://gems.github.com
gem install paulj-hookout

It can also be installed manually with:

git clone git://github.com/paulj/hookout.git
cd hookout
rake build install

Running an application via the hookout helper

Hookout provides a Rack (rack.rubyforge.org) adapter, allowing any standard Rack application to be made available. It also bundles a script called hookout that will start up an instance of Thin using ReverseHTTP as a backend. This section will cover running a simple Sinatra application with the hookout helper.

Firstly, say we have a simple Sinatra application (called simple-app.rb):

require 'rubygems'
require 'sinatra'

get '/' do
  "Hello World"
end

To run with the hookout adapter, you'll need a simple rackup configuration file. Create a config.ru such as:

require 'simple-app'

set :run, false

run Sinatra::Application

From the command line, you can now start this application with a command line such as:

hookout -a http://www.reversehttp.net/reversehttp -n simple-ruby-app -R config.ru start

Thin should boot, and provide output such as:

>> Thin web server (v1.0.0 codename That's What She Said)
>> Maximum connections set to 1024
>> Listening on simple-ruby-app via http://www.reversehttp.net/reversehttp, CTRL+C to stop
Bound to location http://simple-ruby-app.www.reversehttp.net/

You can now visit simple-ruby-app.www.reversehttp.net to see you application.

Configuring Sinatra to use Hookout as the default server

To make a Sintatra application run Hookout instead of thin, a simple script such as the following can be used:

require 'rubygems'
require 'sinatra'
require 'hookout'

set :server, 'hookout'
set :host, 'http://www.reversehttp.net/reversehttp'
set :port, 'standalone-ruby-app'

get '/' do
  "Hello World"
end

This instructs Sinatra to start Hookout as the Rack adapter; and informs hookout that it should use the public www.reversehttp.net server; and informs hookout that it should request the “standalone-ruby-app” space on that server for this application. (Note: To prevent problems, it is HIGHLY recommended to change this to something more unique before trying this!).

You can now run the application with:

ruby test-app.rb

You should see it startup with something like:

== Sinatra/0.9.2 has taken the stage on test-ruby-app for development with backup from Hookout
Location changed to http://standalone-ruby-app.www.reversehttp.net/

You can now visit standalone-ruby-app.www.reversehttp.net, and see you own Sinatra app serving pages!

Software License

Copyright (c) 2008, 2009 Paul Jones <paulj@lshift.net>
Copyright (c) 2008, 2009 LShift Ltd. <query@lshift.net>

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy,
modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.