Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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