1SHOTGUN(1) SHOTGUN(1)
2
6 shotgun - reloading rack development server
7
9 shotgun [options] [rackup-file]
10
12 Shotgun is a simple process-per-request Rack http://rack.ruby‐
13 forge.org/doc/README.html server designed for use in development envi‐
14 ronments. Each time a request is received, shotgun forks, loads the
15 rackup-file, processes a single request and exits. The result is appli‐
16 cation-wide reloading of all configuration, source files, and templates
17 without the need for complex application-level reloading logic.
18 When no rackup-file is given, shotgun uses the config.ru file in the
20 current working directory.
21
23 Shotgun runs at http://127.0.0.1:9393 by default. The following options
24 control server behavior:
25 -E, --env=environment
27 Sets the RACK_ENV environment variable to environment and
28 selects the default set of utility middleware. When environment
29 is ´development´, shotgun inserts the Rack::Lint and Rack::Com‐
30 monLogger middleware components; when environment is ´produc‐
31 tion´ or ´deployed´, Rack::CommonLogger is inserted; otherwise,
32 no utility middleware are inserted.
33 -P, --public=path
35 Serve requests for static files that exist under path from the
36 shotgun master process without forking a worker process. This
37 option is automatically enabled when a ./public directory is
38 detected, but can be configured explicitly for non-conventional
39 static file directory locations.
40 Setting this option appropriately can severely improve overall
42 page load times for applications with many static assets.
43 -s, --server=mongrel|webrick|thin|other
45 The Rack server handler implementation used to serve requests.
46 Supported values include: mongrel, webrick, and thin. By
47 default, shotgun first tries to use mongrel and falls back to
48 webrick if mongrel is not available.
49 -o, --host=addr
51 The hostname or address of the interface the HTTP server should
52 bind to. Default: 127.0.0.1.
53 -p, --port=port
55 The port the HTTP server should bind to. Default: 9393.
56 -O, --browse
58 Open browser at http://host:port/ immediately after the server
59 is started.
60 Ruby environment related options:
62 -r, --require library
64 Require library before loading the application and starting the
65 server. This can be used to load a portion of the application
66 code in the master process so it doesn´t need to be loaded in
67 the child. See PRELOADING][] for more information on this
68 approach.
69 -e, --eval command
71 Evaluate arbitrary command within the shotgun master Ruby inter‐
72 preter. command is evaluated as program arguments are parsed.
73 Multiple -e arguments are allowed.
74 -d, --debug
76 Turns on debug mode. $DEBUG will be set true.
77 -w, --warn
79 Enable verbose mode without printing version message at the
80 beginning. It sets the $VERBOSE variable to true.
81 -I, --include path
83 Add path to the Ruby load path ($LOAD_PATH). May be used more
84 than once.
85 Miscellaneous:
87 -h, --help
89 Show usage message and exit.
90 --version
92 Show the Rack version and exit.
93
95 It´s possible to load support libraries and portions of the application
96 in the shotgun master process to reduce the amount of work that needs
97 to be done for each request in worker processes. There´s two ways of
98 accomplishing this: either by specifying one or more --require (-r)
99 arguments or through the use of a shotgun.rb file.
100 During start up, shotgun looks for a shotgun.rb or config/shotgun.rb
102 file. If either file is found, it´s loaded into the shotgun master
103 process. Code at the top-level of the shotgun.rb is run once on
104 startup, so just require whatever you want to preload. It´s also possi‐
105 ble to register callbacks to run before each request in either the mas‐
106 ter or child worker process:
107 after_fork { stuff }
109 Run stuff in the shotgun child worker process immediately after
110 forking. Any files or socket connections opened in the master
111 process should be closed / re-established by an after_fork
112 block.
113 before_fork { stuff }
115 Run stuff in the shotgun master process on each request before
116 forking the child worker process. This is typically less useful
117 than after_fork, but provided for completeness.
118 Example config/shotgun.rb file from the main github.com rails project:
120 # make sure the load path includes RAILS_ROOT
124 ENV[´RAILS_ROOT´] ||= File.expand_path(´../..´, __FILE__)
125 $:.unshift ENV[´RAILS_ROOT´]
126 # bring in the base rails environment and some libraries
128 require ´config/environment´
129 require ´google-charts´
130 require ´aws-s3´
131 # disable Rails´s built in class reloading
133 Rails.configuration.cache_classes = true
134 # reset database and redis connections in workers
136 after_fork do
137 ActiveRecord::Base.establish_connection
138 CHIMNEY.client = $redis
139 end
140
144 Shotgun is distributed as a gem package at rubygems.org:
145 http://rubygems.org/gems/shotgun
147 gem install shotgun
148 The rack package is required. The mongrel package is recommended.
150
152 Fork and report issues at github.com:
153 http://github.com/rtomayko/shotgun/
155 git clone git://github.com/rtomayko/shotgun.git
156
158 Version 0.9 (2011 February 24)
159 · http://github.com/rtomayko/shotgun/compare/0.8...0.9
160 · Various Ruby 1.9.2 fixes.
162 · Handle application class names consisting of multiple words.
164 Version 0.8 (2010 June 24)
168 · http://github.com/rtomayko/shotgun/compare/0.7...0.8
169 · Preloading support. The shotgun.rb or config/shotgun.rb file is
171 loaded at startup and may require libraries and register callbacks
172 for fork events. See the section on PRELOADING.
173 · Fix starting with the Thin handler (shotgun -s thin)
175 · Actually include the shotgun(1) roff manual.
177 Version 0.7 (2010 June 22)
181 · http://github.com/rtomayko/shotgun/compare/0.6...0.7
182 · Static files now served from the shotgun master process, making
184 shotgun tolerable for apps with many/unbundled static assets.
185 · Added --public (-P) for specifying a non-standard root / public
187 directory.
188 · Response bodies are now streamed over the master < worker pipe
190 instead of being marshalled. Improves performance with large
191 response bodies, and reduces shotgun master process RES usage.
192 · GET /favicon.ico requests are served an empty response by the shot‐
194 gun master process. Prevents the need to fork a worker process.
195 · INT, TERM, QUIT now properly trigger server shutdown. The second
197 INT, TERM, QUIT causes the master process to exit hard.
198 · Non .ru config files (e.g., sinatra app files) may now define com‐
200 mand line options in the same way as .ru files: by including a #\
201 -p 5555 ... line.
202 Versions < 0.7 (2009-2010)
206 · http://github.com/rtomayko/shotgun/commits/0.6
207
211 ruby(1)
212Shotgun 0.9 February 2011 SHOTGUN(1)