README.rdoc

Path: README.rdoc
Last Update: Thu Dec 22 21:26:27 +0000 2016

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.

[Validate]