shotgun - reloading rack development server
shotgun [options] [rackup-file]
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.
Shotgun runs at http://127.0.0.1:9393 by default. The following options
control server behavior:
-E, --env=environmentSets 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=pathServe 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|otherThe 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=addrThe hostname or address of the interface the HTTP server should bind to.
Default: 127.0.0.1.
-p, --port=portThe port the HTTP server should bind to. Default: 9393.
-O, --browseOpen browser at http://host:port/ immediately after the server is started.
Ruby environment related options:
-r, --require libraryRequire 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 commandEvaluate arbitrary command within the shotgun master Ruby interpreter.
command is evaluated as program arguments are parsed. Multiple -e
arguments are allowed.
-d, --debugTurns on debug mode. $DEBUG will be set true.
-w, --warnEnable verbose mode without printing version message at the beginning. It
sets the $VERBOSE variable to true.
-I, --include pathAdd path to the Ruby load path ($LOAD_PATH). May be used more than once.
Miscellaneous:
-h, --helpShow usage message and exit.
--versionShow the Rack version and exit.
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
Shotgun is distributed as a gem package at rubygems.org:
http://rubygems.org/gems/shotgun
gem install shotgun
The rack package is required. The mongrel package is recommended.
Fork and report issues at github.com:
http://github.com/rtomayko/shotgun/
git clone git://github.com/rtomayko/shotgun.git
Various Ruby 1.9.2 fixes.
Handle application class names consisting of multiple words.
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.
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 < 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.