Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 264 lines (183 sloc) 9.546 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
4f34800 Tobias Noiges Fix a typo on the configuration page
noiges authored
20 In its simplest form, the `set` method takes a setting name and value and
1838ae1 Ryan Tomayko options are now settings
rtomayko authored
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
be6607b Matt Wildig Update bind docs in configuration.markdown
mattwildig authored
193 when the `:run` setting is enabled. The default value in the development
194 environment is `'localhost'` which means the server is only available from the
195 local machine. In other environments the default is `'0.0.0.0'`, which causes
196 the server to listen on all available interfaces.
7843e6f Ryan Tomayko Document all built-in options, set, enable, and disable [#78]
rtomayko authored
197
be6607b Matt Wildig Update bind docs in configuration.markdown
mattwildig authored
198 To listen on all interfaces in the development environment (for example if you
199 want to test from other computers in your local network) use:
200
201 set :bind, '0.0.0.0'
202
203 This can also be set from the command line with the `-o` option. If you set the
204 bind option in your application it will override anything set on the command
205 line.
7843e6f Ryan Tomayko Document all built-in options, set, enable, and disable [#78]
rtomayko authored
206
207 ### `:port` - server port
208
209 The port that should be used when starting the built-in web server when the
1838ae1 Ryan Tomayko options are now settings
rtomayko authored
210 `: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
211 explicitly:
212
213 set :port, 9494
214
215 ### `:app_file` - main application file
216
1838ae1 Ryan Tomayko options are now settings
rtomayko authored
217 The `:app_file` setting is used to calculate the default `:root`,
ea9abb3 Konstantin Haase public_directory => public_folder, fixes #52
rkh authored
218 `: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
219 default detection heuristic by setting the `:app_file` explicitly from
220 within the main application file:
221
222 set :app_file, __FILE__
223
d114da1 Damian Janowski Remove trails of reload option.
djanowski authored
224 It's also used to detect whether Sinatra should boot a web server when
225 using [classic-style](http://www.sinatrarb.com/extensions.html#background)
226 applications.
227
7843e6f Ryan Tomayko Document all built-in options, set, enable, and disable [#78]
rtomayko authored
228 ### `:dump_errors` - log exception backtraces to `STDERR`
229
230 Boolean specifying whether backtraces are written to `STDERR` when an
1838ae1 Ryan Tomayko options are now settings
rtomayko authored
231 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
232 default in classic style apps. Disable with:
233
234 set :dump_errors, false
235
236 ### `:raise_errors` - allow exceptions to propagate outside of the app
237
238 Boolean specifying whether exceptions raised from routes and filters should
239 escape the application. When disabled, exceptions are rescued and mapped to
240 error handlers which typically set a 5xx status code and render a custom
1838ae1 Ryan Tomayko options are now settings
rtomayko authored
241 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
242 raised outside of the application where it may be handled by the server
243 handler or Rack middleware, such as [`Rack::ShowExceptions`][se] or
244 [`Rack::MailExceptions`][me].
245
246 [se]: http://rack.rubyforge.org/doc/classes/Rack/ShowExceptions.html
640d5da Soon Van Shakedown whole bunch of links and repo URLs
randomecho authored
247 [me]: https://github.com/rack/rack-contrib/blob/master/lib/rack/contrib/mailexceptions.rb
7843e6f Ryan Tomayko Document all built-in options, set, enable, and disable [#78]
rtomayko authored
248
249 ### `:lock` - ensure single request concurrency with a mutex lock
250
251 Sinatra can be used in threaded environments where more than a single
252 request is processed at a time. However, not all applications and libraries
253 are thread-safe and may cause intermittent errors or general weirdness.
1838ae1 Ryan Tomayko options are now settings
rtomayko authored
254 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
255 lock, ensuring that only a single request is processed at a time.
256
1838ae1 Ryan Tomayko options are now settings
rtomayko authored
257 The `:lock` setting is disabled by default.
91169c9 Ryan Tomayko update options/config doc for 1.0 changes
rtomayko authored
258
259 ### `:show_exceptions` - enable classy error pages
260
261 Enable error pages that show backtrace and environment information when
262 an unhandled exception occurs. Enabled in development environments by
263 default.
Something went wrong with that request. Please try again.