cims-configurationserver/vendor/bundle/ruby/1.9.1/gems/shotgun-0.9/man/shotgun.1.ronn

shotgun(1) -- reloading rack development server
===============================================

## SYNOPSIS

`shotgun` [<options>] [<rackup-file>]

## DESCRIPTION

**Shotgun** is a simple process-per-request [Rack][] server designed for use in
development environments. Each time a request is received, `shotgun` forks,
loads the <rackup-file>, processes a single request and exits.  The result is
application-wide reloading of all configuration, source files, and templates
without the need for complex application-level reloading logic.

When no <rackup-file> is given, `shotgun` uses the `config.ru` file in the
current working directory.

## OPTIONS

Shotgun runs at `http://127.0.0.1:9393` by default. The following options
control server behavior:

 * `-E`, `--env`=<environment>:
   Sets the `RACK_ENV` environment variable to <environment> and selects
   the default set of utility middleware. When <environment> is 'development',
   shotgun inserts the `Rack::Lint` and `Rack::CommonLogger` middleware
   components; when <environment> is 'production' or 'deployed',
   `Rack::CommonLogger` is inserted; otherwise, no utility middleware are
   inserted.

 * `-P`, `--public`=<path>:
   Serve requests for static files that exist under <path> from the shotgun
   master process without forking a worker process. This option is
   automatically enabled when a `./public` directory is detected, but can be
   configured explicitly for non-conventional static file directory locations.

   Setting this option appropriately can severely improve overall page load
   times for applications with many static assets.

 * `-s`, `--server`=<mongrel>|<webrick>|<thin>|<other>:
   The Rack server handler implementation used to serve requests. Supported
   values include: `mongrel`, `webrick`, and `thin`. By default, shotgun first
   tries to use `mongrel` and falls back to `webrick` if mongrel is not
   available.

 * `-o`, `--host`=<addr>:
   The hostname or address of the interface the HTTP server should bind to.
   Default: `127.0.0.1`.

 * `-p`, `--port`=<port>:
   The port the HTTP server should bind to. Default: `9393`.

 * `-O`, `--browse`:
   Open browser at http://<host>:<port>/ immediately after the server
   is started.

Ruby environment related options:

 * `-r`, `--require` <library>:
   Require <library> before loading the application and starting the server.
   This can be used to load a portion of the application code in the master
   process so it doesn't need to be loaded in the child. See [PRELOADING]][]
   for more information on this approach.

 * `-e`, `--eval` <command>:
   Evaluate arbitrary <command> within the shotgun master Ruby interpreter.
   <command> is evaluated as program arguments are parsed. Multiple `-e`
   arguments are allowed.

 * `-d`, `--debug`:
   Turns on debug mode. `$DEBUG` will be set `true`.

 * `-w`, `--warn`:
   Enable verbose mode without printing version message at the beginning. It
   sets the `$VERBOSE` variable to true.

 * `-I`, `--include` <path>:
   Add <path> to the Ruby load path (`$LOAD_PATH`). May be used more than once.

Miscellaneous:

 * `-h`, `--help`:
   Show usage message and exit.

 * `--version`:
   Show the Rack version and exit.

## PRELOADING

It's possible to load support libraries and portions of the application in the
shotgun master process to reduce the amount of work that needs to be done for
each request in worker processes. There's two ways of accomplishing this: either
by specifying one or more `--require` (`-r`) arguments or through the use of a
`shotgun.rb` file.

During start up, shotgun looks for a `shotgun.rb` or `config/shotgun.rb` file.
If either file is found, it's loaded into the shotgun master process. Code at
the top-level of the `shotgun.rb` is run once on startup, so just require
whatever you want to preload. It's also possible to register callbacks to run
before each request in either the master or child worker process:

  * `after_fork {` <stuff> `}`:
    Run <stuff> in the shotgun child worker process immediately after forking.
    Any files or socket connections opened in the master process should be
    closed / re-established by an `after_fork` block.

  * `before_fork {` <stuff> `}`:
    Run <stuff> in the shotgun master process on each request before forking
    the child worker process. This is typically less useful than `after_fork`,
    but provided for completeness.

Example `config/shotgun.rb` file from the main github.com rails project:

    # make sure the load path includes RAILS_ROOT
    ENV['RAILS_ROOT'] ||= File.expand_path('../..', __FILE__)
    $:.unshift ENV['RAILS_ROOT']

    # bring in the base rails environment and some libraries
    require 'config/environment'
    require 'google-charts'
    require 'aws-s3'

    # disable Rails's built in class reloading
    Rails.configuration.cache_classes = true

    # reset database and redis connections in workers
    after_fork do
      ActiveRecord::Base.establish_connection
      CHIMNEY.client = $redis
    end

## INSTALLING

Shotgun is distributed as a gem package at rubygems.org:

<http://rubygems.org/gems/shotgun><br>
`gem install shotgun`

The `rack` package is required. The `mongrel` package is recommended.

## CONTRIBUTING

Fork and report issues at github.com:

<http://github.com/rtomayko/shotgun/><br>
`git clone git://github.com/rtomayko/shotgun.git`

## VERSION HISTORY

### Version 0.9 (2011 February 24)

 * <http://github.com/rtomayko/shotgun/compare/0.8...0.9>

 * Various Ruby 1.9.2 fixes.

 * Handle application class names consisting of multiple words.

### Version 0.8 (2010 June 24)

 * <http://github.com/rtomayko/shotgun/compare/0.7...0.8>

 * Preloading support. The `shotgun.rb` or `config/shotgun.rb` file is
   loaded at startup and may require libraries and register callbacks
   for fork events. See the section on [PRELOADING][].

 * Fix starting with the Thin handler (`shotgun -s thin`)

 * Actually include the shotgun(1) roff manual.

### Version 0.7 (2010 June 22)

 * <http://github.com/rtomayko/shotgun/compare/0.6...0.7>

 * Static files now served from the shotgun master process, making
   shotgun tolerable for apps with many/unbundled static assets.

 * Added `--public` (`-P`) for specifying a non-standard root / public
   directory.

 * Response bodies are now streamed over the master &lt; worker pipe
   instead of being marshalled. Improves performance with large response
   bodies, and reduces shotgun master process RES usage.

 * GET /favicon.ico requests are served an empty response by the shotgun
   master process. Prevents the need to fork a worker process.

 * `INT`, `TERM`, `QUIT` now properly trigger server shutdown. The second
   `INT`, `TERM`, `QUIT` causes the master process to exit hard.

 * Non `.ru` config files (e.g., sinatra app files) may now define command
   line options in the same way as `.ru` files: by including a
   `#\ -p 5555 ...` line.

### Versions &lt; 0.7 (2009-2010)

 * <http://github.com/rtomayko/shotgun/commits/0.6>

## SEE ALSO

ruby(1)