Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 291 lines (203 sloc) 10.681 kB
7843e6f @rtomayko Document all built-in options, set, enable, and disable [#78]
rtomayko authored
1 ---
2 title: 'Sinatra: Options and Configuration'
3 layout: default
4 id: configuration
5 ---
6
7 Options and Configuration
8 =========================
9
10 Sinatra includes a number of built-in options that control whether certain
11 features are enabled. Options are application-level variables that are
12 modified using one of the `set`, `enable`, or `disable` methods and are
13 available within the request context via the `options` object. Applications
14 are free to set custom options as well as the default, built-in options
15 provided by the framework.
16
17 Using `set`, `enable`, and `disable`
18 ------------------------------------
19
20 In its simplest form, the `set` method takes an option name and value and
21 creates an attribute on the application. Options can be accessed within
22 requests via the `options` object:
23
24 {% highlight ruby %}
25 set :foo, 'bar'
26
27 get '/foo' do
28 "foo is set to " + options.foo
29 end
30 {% endhighlight %}
31
32 ### Deferring option evaluation
33
34 When the option value is a `Proc`, evaluation is performed when the option
35 is read so that other options may be used to calculate the option value:
36
37 {% highlight ruby %}
38 set :foo, 'bar'
39 set :baz, Proc.new { "Hello " + foo }
40
41 get '/baz' do
42 "baz is set to " + options.baz
43 end
44 {% endhighlight %}
45
46 The `/baz` response should come as "baz is set to Hello bar" unless the
47 `foo` option is modified.
48
49 ### Setting multiple options
50
51 Multiple options can be set by passing a Hash to `set`. The previous example
52 could be rewritten with:
53
54 {% highlight ruby %}
55 set :foo => 'bar', :baz => Proc.new { "Hello " + foo }
56 {% endhighlight %}
57
58 ### Setting multiple boolean options with `enable` and `disable`
59
60 The `enable` and `disable` methods are sugar for setting a list of options
61 to `true` or `false`, respectively. The following two code examples are
62 equivalent:
63
64 {% highlight ruby %}
65 enable :sessions, :clean_trace
66 disable :logging, :dump_errors, :some_custom_option
67 {% endhighlight %}
68
69 Using `set`:
70
71 {% highlight ruby %}
72 set :sessions, true
73 set :clean_trace, true
74 set :logging, false
75 set :dump_errors, false
76 set :some_custom_option, false
77 {% endhighlight %}
78
79 Built-in Options
80 ----------------
81
82 ### `:environment` - configuration/deployment environment
83
84 A symbol specifying the deployment environment; typically set to one of
85 `:development`, `:test`, or `:production`. The `:environment` defaults to
86 the value of the `RACK_ENV` environment variable (`ENV['RACK_ENV']`), or
87 `:development` when no `RACK_ENV` environment variable is set.
88
89 The `:environment` option effects the default values of various other
90 options. For instance, application reloading (`:reload`) is enabled by
91 default in the development environment.
92
93 The environment can be set explicitly:
94
95 set :environment, :production
96
97 ### `:sessions` - enable/disable cookie based sessions
98
99 Support for encrypted, cookie-based sessions are included with Sinatra but
100 are disabled by default. Enable them with:
101
102 set :sessions, true
103
104 Sessions are implemented by inserting the [`Rack::Session::Cookie`][c]
105 component into the application's middleware pipeline.
106
107 [c]: http://rack.rubyforge.org/doc/classes/Rack/Session/Cookie.html
108
109 ### `:logging` - log requests to `STDERR`
110
111 Writes a single line to `STDERR` in Apache common log format when enabled.
112 This option is enabled by default in classic style apps and disabled by
113 default in `Sinatra::Base` subclasses.
114
115 Internally, the [`Rack::CommonLogger`][cl] component is used to generate
116 log messages.
117
118 [cl]: http://rack.rubyforge.org/doc/classes/Rack/CommonLogger.html
119
120 ### `:methodoverride` - enable/disable the POST `_method` hack
121
122 Boolean specifying whether the HTTP POST `_method` parameter hack should be
123 enabled. When `true`, the actual HTTP request method is overridden by the
124 value of the `_method` parameter included in the POST body. The `_method`
125 hack is used to make POST requests look like other request methods (e.g.,
126 `PUT`, `DELETE`) and is typically only needed in shitty environments -- like
127 HTML form submission -- that do not support the full range of HTTP methods.
128
129 The POST `_method` hack is implemented by inserting the
130 [`Rack::MethodOverride`][mo] component into the middleware pipeline.
131
132 [mo]: http://rack.rubyforge.org/doc/classes/Rack/MethodOverride.html
133
134 ### `:reload` - enable/disable automatic source code reloading
135
136 The `:reload` option determines whether the main application file is
137 reloaded before processing each request. Automatic reloading is enabled by
138 default when running under the development environment (see the
139 `:environment` option) and a valid `:app_file` was detected.
140
141 To explicitly enable reloading, it's best to set both the `:reload` and
142 `:app_file` options as follows:
143
144 set :app_file, __FILE__
145 set :reload, true
146
147 Sinatra implements reloading by clearing all routes, filters, templates, and
148 error handlers and then calling `Kernel::load` on the main application file.
149 Note that files loaded by the application file using `Kernel::require` are
150 not automatically reloaded. You can cause other files to be reloaded by
151 using `Kernel::load` instead of `Kernel::require` from within the main
152 application file.
153
154 ### `:root` - The application's root directory
155
156 The directory used as a base for the application. By default, this is
157 assumed to be the directory containing the main application file
158 (`:app_file` option). The root directory is used to construct the default
159 `:public` and `:views` options. A common idiom is to set the `:root` option
160 explicitly in the main application file as follows:
161
162 set :root, File.dirname(__FILE__)
163
164 ### `:static` - enable/disable static file routes
165
166 Boolean that determines whether static files should be served from the
167 application's public directory (see the `:public` option). When `:static` is
168 truthy, Sinatra will check if a static file exists and serve it before
169 checking for a matching route.
170
171 The `:static` option is enabled by default in classic style apps and
172 disabled by default in `Sinatra::Base` subclasses.
173
174 ### `:public` - static files directory
175
176 A string specifying the directory where static files should be served from.
177 By default, this is assumed to be a directory named "public" within the root
178 directory (see the `:root` option). You can set the public directory
179 explicitly with:
180
181 set :public, '/var/www'
182
183 The best way to specify an alternative directory name within the root of the
184 application is to use a deferred value that references the `:root` option:
185
186 set :public, Proc.new { File.join(root, "static") }
187
188 ### `:views` - view template directory
189
190 A string specifying the directory where view templates are located. By
191 default, this is assumed to be a directory named "views" within the
192 application's root directory (see the `:root` option). The best way to
193 specify an alternative directory name within the root of the application is
194 to use a deferred value that references the `:root` option:
195
d07281a @rtomayko Fix 'set :views' typo
rtomayko authored
196 set :views, Proc.new { File.join(root, "templates") }
7843e6f @rtomayko Document all built-in options, set, enable, and disable [#78]
rtomayko authored
197
198 ### `:run` - enable/disable the built-in web server
199
200 Boolean specifying whether the built-in web server is started after the app
201 is fully loaded. By default, this option is enabled only when the
202 `:app_file` matches `$0`. i.e., when running a Sinatra app file directly
203 with `ruby myapp.rb`. To disable the built-in web server:
204
205 set :run, false
206
207 ### `:server` - handler used for built-in web server
208
209 String or Array of Rack server handler names. When the `:run` option is
210 enabled, Sinatra will run through the list and start a server with the
211 first available handler. The `:server` option is set as follows by default:
212
213 set :server, %w[thin mongrel webrick]
214
215 ### `:host` - server hostname or IP address
216
217 String specifying the hostname or IP address of the interface to listen on
218 when the `:run` option is enabled. The default value -- `'0.0.0.0'` -- causes
219 the server to listen on all available interfaces. To listen on the
220 loopback interface only, use:
221
222 set :host, 'localhost'
223
224 ### `:port` - server port
225
226 The port that should be used when starting the built-in web server when the
227 `:run` option is enabled. The default port is `4567`. To set the port
228 explicitly:
229
230 set :port, 9494
231
232 ### `:app_file` - main application file
233
234 The ruby source file that's reloaded before each request when the `:reload`
235 option is enabled. This is set to the first source file that invokes
236 `require 'sinatra'` by default.
237
238 The `:app_file` option is also used to calculate the default `:root`,
239 `:public`, and `:views` option values. A common idiom is to override the
240 default detection heuristic by setting the `:app_file` explicitly from
241 within the main application file:
242
243 set :app_file, __FILE__
244
245 ### `:dump_errors` - log exception backtraces to `STDERR`
246
247 Boolean specifying whether backtraces are written to `STDERR` when an
248 exception is raised from a route or filter. This option is enabled by
249 default in classic style apps. Disable with:
250
251 set :dump_errors, false
252
253 ### `:clean_trace` - scrub library entries from backtraces
254
255 When the `:clean_trace` option is enabled, library/framework entries are
256 removed from exception backtraces before being written to `STDERR`
257 (see `:dump_errors` option) or being displayed on the development mode
258 error page.
259
260 The `:clean_trace` option is enabled by default in all environments. Disable
261 it to get full exception backtraces:
262
263 set :clean_trace, false
264
265 ### `:raise_errors` - allow exceptions to propagate outside of the app
266
267 Boolean specifying whether exceptions raised from routes and filters should
268 escape the application. When disabled, exceptions are rescued and mapped to
269 error handlers which typically set a 5xx status code and render a custom
270 error page. Enabling the `:raise_errors` option causes exceptions to be
271 raised outside of the application where it may be handled by the server
272 handler or Rack middleware, such as [`Rack::ShowExceptions`][se] or
273 [`Rack::MailExceptions`][me].
274
275 [se]: http://rack.rubyforge.org/doc/classes/Rack/ShowExceptions.html
276 [me]: http://github.com/rack/rack-contrib/blob/master/lib/rack/contrib/mailexceptions.rb
277
278 The `:raise_errors` option is disabled by default for classic style apps
279 and enabled by default for `Sinatra::Base` subclasses.
280
281 ### `:lock` - ensure single request concurrency with a mutex lock
282
283 Sinatra can be used in threaded environments where more than a single
284 request is processed at a time. However, not all applications and libraries
285 are thread-safe and may cause intermittent errors or general weirdness.
286 Enabling the `:lock` option causes all requests to synchronize on a mutex
287 lock, ensuring that only a single request is processed at a time.
288
289 The `:lock` option is disabled by default unless the `:reload` option is
290 enabled -- source code reloading must be synchronized.
Something went wrong with that request. Please try again.