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.
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
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.
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!
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.