Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 269 lines (186 sloc) 9.546 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 can be set explicitly:
90
91 set :environment, :production
92
93 ### `:sessions` - enable/disable cookie based sessions
94
95 Support for encrypted, cookie-based sessions are included with Sinatra but
96 are disabled by default. Enable them with:
97
98 set :sessions, true
99
100 Sessions are implemented by inserting the [`Rack::Session::Cookie`][c]
101 component into the application's middleware pipeline.
102
103 [c]: http://rack.rubyforge.org/doc/classes/Rack/Session/Cookie.html
104
105 ### `:logging` - log requests to `STDERR`
106
107 Writes a single line to `STDERR` in Apache common log format when enabled.
108 This option is enabled by default in classic style apps and disabled by
109 default in `Sinatra::Base` subclasses.
110
111 Internally, the [`Rack::CommonLogger`][cl] component is used to generate
112 log messages.
113
114 [cl]: http://rack.rubyforge.org/doc/classes/Rack/CommonLogger.html
115
cc49f2c @sr methodoverride => method_override
sr authored
116 ### `:method_override` - enable/disable the POST `_method` hack
7843e6f @rtomayko Document all built-in options, set, enable, and disable [#78]
rtomayko authored
117
118 Boolean specifying whether the HTTP POST `_method` parameter hack should be
119 enabled. When `true`, the actual HTTP request method is overridden by the
120 value of the `_method` parameter included in the POST body. The `_method`
121 hack is used to make POST requests look like other request methods (e.g.,
122 `PUT`, `DELETE`) and is typically only needed in shitty environments -- like
123 HTML form submission -- that do not support the full range of HTTP methods.
124
125 The POST `_method` hack is implemented by inserting the
126 [`Rack::MethodOverride`][mo] component into the middleware pipeline.
127
128 [mo]: http://rack.rubyforge.org/doc/classes/Rack/MethodOverride.html
129
130 ### `:root` - The application's root directory
131
132 The directory used as a base for the application. By default, this is
133 assumed to be the directory containing the main application file
134 (`:app_file` option). The root directory is used to construct the default
135 `:public` and `:views` options. A common idiom is to set the `:root` option
136 explicitly in the main application file as follows:
137
138 set :root, File.dirname(__FILE__)
139
140 ### `:static` - enable/disable static file routes
141
142 Boolean that determines whether static files should be served from the
143 application's public directory (see the `:public` option). When `:static` is
144 truthy, Sinatra will check if a static file exists and serve it before
145 checking for a matching route.
146
91169c9 @rtomayko update options/config doc for 1.0 changes
rtomayko authored
147 The `:static` option is enabled by default when the `public` directory
148 exists.
7843e6f @rtomayko Document all built-in options, set, enable, and disable [#78]
rtomayko authored
149
150 ### `:public` - static files directory
151
152 A string specifying the directory where static files should be served from.
153 By default, this is assumed to be a directory named "public" within the root
154 directory (see the `:root` option). You can set the public directory
155 explicitly with:
156
157 set :public, '/var/www'
158
159 The best way to specify an alternative directory name within the root of the
160 application is to use a deferred value that references the `:root` option:
161
162 set :public, Proc.new { File.join(root, "static") }
163
164 ### `:views` - view template directory
165
166 A string specifying the directory where view templates are located. By
167 default, this is assumed to be a directory named "views" within the
168 application's root directory (see the `:root` option). The best way to
169 specify an alternative directory name within the root of the application is
170 to use a deferred value that references the `:root` option:
171
d07281a @rtomayko Fix 'set :views' typo
rtomayko authored
172 set :views, Proc.new { File.join(root, "templates") }
7843e6f @rtomayko Document all built-in options, set, enable, and disable [#78]
rtomayko authored
173
174 ### `:run` - enable/disable the built-in web server
175
176 Boolean specifying whether the built-in web server is started after the app
177 is fully loaded. By default, this option is enabled only when the
178 `:app_file` matches `$0`. i.e., when running a Sinatra app file directly
179 with `ruby myapp.rb`. To disable the built-in web server:
180
181 set :run, false
182
183 ### `:server` - handler used for built-in web server
184
185 String or Array of Rack server handler names. When the `:run` option is
186 enabled, Sinatra will run through the list and start a server with the
187 first available handler. The `:server` option is set as follows by default:
188
189 set :server, %w[thin mongrel webrick]
190
191 ### `:host` - server hostname or IP address
192
193 String specifying the hostname or IP address of the interface to listen on
194 when the `:run` option is enabled. The default value -- `'0.0.0.0'` -- causes
195 the server to listen on all available interfaces. To listen on the
196 loopback interface only, use:
197
198 set :host, 'localhost'
199
200 ### `:port` - server port
201
202 The port that should be used when starting the built-in web server when the
203 `:run` option is enabled. The default port is `4567`. To set the port
204 explicitly:
205
206 set :port, 9494
207
208 ### `:app_file` - main application file
209
d114da1 @djanowski Remove trails of reload option.
djanowski authored
210 The `:app_file` option is used to calculate the default `:root`,
7843e6f @rtomayko Document all built-in options, set, enable, and disable [#78]
rtomayko authored
211 `:public`, and `:views` option values. A common idiom is to override the
212 default detection heuristic by setting the `:app_file` explicitly from
213 within the main application file:
214
215 set :app_file, __FILE__
216
d114da1 @djanowski Remove trails of reload option.
djanowski authored
217 It's also used to detect whether Sinatra should boot a web server when
218 using [classic-style](http://www.sinatrarb.com/extensions.html#background)
219 applications.
220
7843e6f @rtomayko Document all built-in options, set, enable, and disable [#78]
rtomayko authored
221 ### `:dump_errors` - log exception backtraces to `STDERR`
222
223 Boolean specifying whether backtraces are written to `STDERR` when an
224 exception is raised from a route or filter. This option is enabled by
225 default in classic style apps. Disable with:
226
227 set :dump_errors, false
228
229 ### `:clean_trace` - scrub library entries from backtraces
230
231 When the `:clean_trace` option is enabled, library/framework entries are
232 removed from exception backtraces before being written to `STDERR`
233 (see `:dump_errors` option) or being displayed on the development mode
234 error page.
235
236 The `:clean_trace` option is enabled by default in all environments. Disable
237 it to get full exception backtraces:
238
239 set :clean_trace, false
240
241 ### `:raise_errors` - allow exceptions to propagate outside of the app
242
243 Boolean specifying whether exceptions raised from routes and filters should
244 escape the application. When disabled, exceptions are rescued and mapped to
245 error handlers which typically set a 5xx status code and render a custom
246 error page. Enabling the `:raise_errors` option causes exceptions to be
247 raised outside of the application where it may be handled by the server
248 handler or Rack middleware, such as [`Rack::ShowExceptions`][se] or
249 [`Rack::MailExceptions`][me].
250
251 [se]: http://rack.rubyforge.org/doc/classes/Rack/ShowExceptions.html
252 [me]: http://github.com/rack/rack-contrib/blob/master/lib/rack/contrib/mailexceptions.rb
253
254 ### `:lock` - ensure single request concurrency with a mutex lock
255
256 Sinatra can be used in threaded environments where more than a single
257 request is processed at a time. However, not all applications and libraries
258 are thread-safe and may cause intermittent errors or general weirdness.
259 Enabling the `:lock` option causes all requests to synchronize on a mutex
260 lock, ensuring that only a single request is processed at a time.
261
d114da1 @djanowski Remove trails of reload option.
djanowski authored
262 The `:lock` option is disabled by default.
91169c9 @rtomayko update options/config doc for 1.0 changes
rtomayko authored
263
264 ### `:show_exceptions` - enable classy error pages
265
266 Enable error pages that show backtrace and environment information when
267 an unhandled exception occurs. Enabled in development environments by
268 default.
Something went wrong with that request. Please try again.