1Dancer2::Config(3) User Contributed Perl Documentation Dancer2::Config(3)
2
6 Dancer2::Config - Configure Dancer2 to suit your needs
7
9 version 0.400001
10
12 The Dancer2 configuration (as implemented by
13 Dancer2::Core::Role::ConfigReader) handles reading and changing the
14 configuration of your Dancer2 apps. This document describes how to
15 manipulate Dancer2's configuration settings (through code or by file),
16 and to document the various settings that are available in Dancer2.
17
19 You can change a setting with the keyword "set":
20 use Dancer2;
22 # changing default settings
24 set port => 8080;
25 set content_type => 'text/plain';
26 set startup_info => 0;
27
29 There's nothing wrong with using "set" to configure your application.
30 In fact you might have some great reasons for doing so. For greater
31 flexibility, ease of deployment, etc., you should also consider
32 extracting those settings into a configuration file.
33 Configuration file path and file names
35 Dancer2 will first look for the file config.EXT (where EXT is the type
36 of configuration file you are using; e.g. ini or json or yml) in the
37 root directory of your application. This is considered your global
38 Dancer2 config file. If you do not care to have separate settings for
39 production and development environments (not a recommended practice!),
40 then this file is all you need.
41 Next, Dancer2 will look for a file called config_local.EXT. This file
43 is typically useful for deployment-specific configuration that should
44 not be checked into source control. For instance, database credentials
45 could be stored in this file. Any settings in this file are merged
46 into the existing configuration such that those with the same name in
47 your local configuration file will take precedence over those settings
48 in the global file.
49 Next, Dancer2 will look in the environments directory for a
51 configuration file specific to the platform you are deploying to
52 (production.EXT or development.EXT, for example). Again, the
53 configuration from the environment is merged with the existing
54 configuration with the deployment config taking precedence.
55 Finally, Dancer2 will look in the environments directory for a local
57 configuration for the specific platform you are deploying to (e.g.
58 production_local.EXT or development_local.EXT) The configuration in
59 this file is merged as before.
60 Much like config_local.EXT, this file would be useful for environment-
62 specific configuration that would not be checked into source control.
63 For instance, when developing an application that talks to multiple
64 services, each developer could have their own URLs to those services
65 stored within their environments/development_local.yaml file.
66 Note, if there is no config.EXT, Dancer2 will not look for a
68 config_local.EXT. The same is true for the local environment
69 configuration.
70 Supported configuration file formats
72 Dancer2 supports any configuration file format that is supported by
73 Config::Any. At the time of this writing, that includes YAML (.yml and
74 .yaml), JSON (.jsn and .json), INI (.ini), Apache-style configurations
75 (.cnf and .conf), XML (.xml), and Perl-style hashes (.pl and .perl).
76 Dancer2 iterates over these file extensions in the order provided by
78 Config::Any and loads any config files that it finds with later
79 configuration information overriding earlier config information. To
80 restrict which file extension Dancer2 looks for, you may set the
81 "DANCER_CONFIG_EXT" envinroment variable to a specific extension and
82 Dancer2 will only look for config files with that extension.
83 Make sure you pick the appropriate extension for your configuration
85 file name, as Dancer2 guesses the type of format based on the file
86 extension.
87 Sample configuration files
89 Note: Not all possibilities are covered here, only the most common
90 options.
91 If you prefer YAML, a sample YAML based config file might look like
93 this:
94 appname: "Hello"
96 charset: "UTF-8"
97 auto_page: 1
98 session: "YAML"
100 serializer: "JSON"
101 plugins:
103 DBIC:
104 default:
105 dsn: dbi:SQLite:db/mydata.db
106 schema_class: Hello::Schema
107 If JSON is more your thing, your file might look more like this:
109 {
111 "appname": "Hello",
112 "charset": "UTF-8",
113 "auto_page": "1",
114 "session": "YAML",
115 "serializer": "JSON",
116 "plugins": {
117 "DBIC": {
118 "default": {
119 "dsn": "dbi:SQLite:db/mydata.db",
120 "schema_class": "Hello::Schema"
121 }
122 }
123 }
124 }
125 If you like Apache configuration files, try something similar to:
127 appname = Hello
129 charset = UTF-8
130 auto_page = 1
131 session = YAML
132 serializer = JSON
133 <plugins>
134 <DBIC>
135 <default>
136 dsn = dbi =SQLite =db/mydata.db
137 schema_class = Hello = =Schema
138 </default>
139 </DBIC>
140 </plugins>
141 INI-style files are deliberately simplistic and not recommended for use
143 in your Dancer2 applications.
144
146 Run mode and listening interface/port
147 host (string)
148 The IP address that the Dancer2 app should bind to. Default is
150 0.0.0.0, i.e. bind to all available interfaces.
151 port (int)
153 The port Dancer2 will listen to.
155 Default value is 3000. This setting can be changed on the command-line
157 with the --port switch.
158 behind_proxy (boolean)
160 If set to true, Dancer2 will look to "X-Forwarded-Protocol" and
162 "X-Forwarded-host" when constructing URLs (for example, when using
163 "redirect" or "host"). This is useful if your application is behind a
164 proxy.
165 Note: If either of these are missing, the values of the proxy server
167 will be used instead. For example, if the client sends a HTTP/1.0
168 request to a proxy that is hosted locally, then "host" will return the
169 value "localhost". In a similar vein, if the client makes a secure
170 connection to the proxy, but the proxy does not pass
171 "X-Forwarded-Protocol", then "base" will return "http://...". For
172 these reasons, it is recommended that the values are hard-configured in
173 the proxy if possible. For Apache this would be:
174 RequestHeader set X_FORWARDED_PROTO "https"
176 RequestHeader set X_FORWARDED_HOST "www.example.com"
177 no_default_middleware (boolean)
179 If set to true, your Dancer2 application will NOT be wrapped with the
181 default PSGI middleware. The default middleware wrappers are:
182 • Plack::Middleware::FixMissingBodyInRedirect
184 • Plack::Middleware::Head
186 Content type / character set
188 content_type (string)
189 The default content type of outgoing content. Default value is
191 'text/html'.
192 charset (string)
194 This setting has multiple effects:
196 • It sets the default charset of outgoing content. "charset=" item
198 will be added to Content-Type response header.
199 • It makes Unicode bodies in HTTP responses of "text/*" types to be
201 encoded to this charset.
202 • It also indicates to Dancer2 in which charset the static files and
204 templates are encoded.
205 • If you're using Dancer2::Plugin::Database, UTF-8 support will
207 automatically be enabled for your database - see "AUTOMATIC UTF-8
208 SUPPORT" in Dancer2::Plugin::Database
209 Default value is empty which means don't do anything. HTTP responses
211 without charset will be interpreted as ISO-8859-1 by most clients.
212 You can cancel any charset processing by specifying your own charset in
214 Content-Type header or by ensuring that response body leaves your
215 handler without Unicode flag set (by encoding it into some 8bit
216 charset, for example).
217 Also, since automatically serialized JSON responses have
219 "application/json" Content-Type, you should always encode them by hand.
220 default_mime_type (string)
222 Dancer2's Dancer2::Core::MIME module uses "application/data" as a
224 default mime type. This setting lets the user change it. For example,
225 if you have a lot of files being served in the public folder that do
226 not have an extension, and are text files, set the "default_mime_type"
227 to "text/plain".
228 Serializing responses
230 serializer (string)
231 When writing a webservice, data serialization/deserialization is a
233 common issue to deal with. Dancer2 can automatically handle that for
234 you, via a serializer.
235 Available serializer engines
237 The following serializers are available, be aware they dynamically
239 depend on Perl modules you may not have on your system.
240 • JSON
242 Requires JSON.
244 • YAML
246 Requires YAML,
248 • XML
250 Requires XML::Simple.
252 • Mutable
254 Will try to find the appropriate serializer using the Content-Type
256 and Accept-type header of the request.
257 Serializer engine
259 The serializer can be configured in a separate "engines" section, like
260 so:
261 serializer: "JSON"
263 engines:
265 serializer:
266 JSON:
267 pretty: 1
268 See documentation for a particular serializer for supported options.
270 File / directory locations
272 environment (string)
273 This is the name of the environment that should be used. Standard
275 Dancer2 applications have a "environments" folder with specific
276 configuration files for different environments (usually development and
277 production environments). They specify different kind of error
278 reporting, deployment details, etc. These files are read after the
279 generic "config.yml" configuration file.
280 appdir (directory)
282 This is the path where your application will live. It's where Dancer2
284 will look by default for your config files, templates and static
285 content.
286 It is typically set by "use Dancer2" to use the same directory as your
288 script.
289 public_dir (directory)
291 This is the directory, where static files are stored. Any existing file
293 in that directory will be served as a static file, before matching any
294 route.
295 See also static_handler.
297 Default: "$appdir/public".
299 static_handler (boolean)
301 This setting have to be declared and set to true if you modify standard
303 "public_dir" location.
304 Default: true if $ENV{DANCER_PUBLIC} is set or "public_dir" is set to
306 "$appdir/public".
307 views (directory)
309 This is the directory where your templates and layouts live. It's the
311 "view" part of MVC (model, view, controller).
312 Default: "$appdir/views".
314 Templating & layouts
316 template
317 Allows you to configure which template engine should be used. For
319 instance, to use Template Toolkit, add the following to "config.yml":
320 template: template_toolkit
322 layout (string)
324 The name of the layout to use when rendering view. Dancer2 will look
326 for a matching template in the directory "$views/layouts".
327 Your can override the default layout using the third argument of the
329 "template" keyword. Check "Dancer2" manpage for details.
330 layout_dir (string)
332 A relative path where the layouts reside inside the "views" directory.
334 layout_dir: actual_layouts
336 Default: layouts.
338 Logging, debugging and error handling
340 startup_info (boolean)
341 If set to true, prints a banner at the server start with information
343 such as versions and the environment (or "dancefloor").
344 Conforms to the environment variable "DANCER_STARTUP_INFO".
346 traces (boolean)
348 If set to true, Dancer2 will display full stack traces when a warning
350 or a die occurs. (Internally sets Carp::Verbose). Default to false.
351 no_server_tokens (boolean)
353 If set to true, Dancer2 will not add an "X-Powered-By" header and also
355 append the Dancer2 version to the "Server" header. Default to false -
356 adding.
357 You can also use the environment variable "DANCER_NO_SERVER_TOKENS".
359 logger (enum)
361 Select which logger to use. For example, to write to log files with
363 Dancer2::Logger::File:
364 logger: File
366 Or to direct log messages to the console from which you started your
368 Dancer2 app with Dancer2::Logger::Console:
369 logger: Console
371 Loggers are configured with a corresponding "Logger engine" section, as
373 shown below.
374 session (enum)
376 This setting lets you enable a session engine for your web application.
378 By default, sessions are disabled in Dancer2, you must choose a session
379 engine to use them.
380 Sessions are configured with a corresponding "Session engine" section,
382 as shown below.
383 show_errors (boolean)
385 Deprecated configuration.
387 Use "show_stacktrace" described below instead.
389 show_stacktrace (boolean)
391 If set to true, Dancer2 will render a detailed debug screen whenever an
393 error is caught. If set to false, Dancer2 will render the default error
394 page, using "$public/$error_code.html" if it exists,
395 "$views/$error_code.tt" or the template specified by the
396 "error_template" setting.
397 The error screen attempts to sanitise sensitive looking information
399 (passwords / card numbers in the request, etc) but you still should not
400 have show_stacktrace enabled whilst in production, as there is still a
401 risk of divulging details.
402 error_template (template path)
404 This setting lets you specify a template to be used in case of runtime
406 error. At the present moment the template (as well as
407 "$views/$error_code.tt" templates) can use four variables:
408 title
410 The error title.
411 content
413 The error specific content (if any).
414 status
416 The HTTP status code throwing that error.
417 exception
419 The stringified exception (e.g. $@) if any.
420 Keep in mind that 'content' and 'exception' can vary depending on the
422 problem.
423 For example:
425 A 404 has an empty 'exception' and 'content' contains the URI that was
427 not found. Unless you do the 404 yourself via "send_error("You chose
428 ... poorly!", 404);", then 'content' is 'You chose ... poorly!'.
429 A 500 because of, say, dividing 0 by 0 will have an empty 'content' and
431 'exception like 'Illegal division by zero at ...'.
432 A 401 from "send_error("You can not know the secret until you sign in
434 grasshopper!", 401);" will have an empty 'exception' and 'content' will
435 contain 'You can not know the secret until you sign in grasshopper!'.
436 Logger engine
438 The logger must be configured in a separate "engines" section, like so:
439 logger: Console
441 engines:
443 logger:
444 Console:
445 log_level: core
446 All loggers support the configuration options below. See documentation
448 for a particular logger for other supported options.
449 log_level
451 This option tells which log messages should be actually logged.
453 Possible values are core, info, debug, warning or error.
454 core : all messages are logged, including some from Dancer2 itself
456 debug : all messages are logged
457 info : only info, warning and error messages are logged
458 warning : only warning and error messages are logged
459 error : only error messages are logged
460 During development, you'll probably want to use "debug" to see your own
462 debug messages, and "core" if you need to see what Dancer2 is doing.
463 In production, you'll likely want "error" or "warning" only, for less-
464 chatty logs.
465 Session engine
467 The session engine is configured in the "engines" section.
468 session: Simple
470 engines:
472 session:
473 Simple:
474 cookie_name: dance.set
475 cookie_duration: '24 hours'
476 cookie_same_site: Lax
477 is_secure: 1
478 is_http_only: 1
479 See Dancer2::Core::Role::SessionFactory for more detailed documentation
481 for these options, or the particular session engine for other supported
482 options.
483 cookie_name
485 The name of the cookie to store the session ID in. Defaults to
487 "dancer.session". This can be overridden by certain session engines.
488 cookie_domain
490 The domain of the cookie. By default there is no domain defined for the
492 cookie.
493 cookie_path
495 The path of the cookie. By default there is no path defined for the
497 cookie.
498 cookie_duration
500 The session expiry time in seconds, or as e.g. "2 hours" (see "expires"
502 in Dancer2::Core::Cookie. By default, there is no specific expiry
503 time.
504 cookie_same_site
506 Restricts the session cookie to a first-party or same-site context.
508 Valid values are "Strict", "Lax", or "None".
509 Refer to RFC6265bis <https://tools.ietf.org/html/draft-ietf-httpbis-
511 cookie-same-site> for further details regarding same-site context.
512 is_secure
514 The user's session ID is stored in a cookie. If the "is_secure"
516 setting is set to a true value, the cookie will be marked as secure,
517 meaning it should only be sent over HTTPS connections.
518 is_http_only
520 This setting defaults to 1 and instructs the session cookie to be
522 created with the "HttpOnly" option active, meaning that JavaScript will
523 not be able to access to its value.
524 auto_page (boolean)
526 For simple pages where you're not doing anything dynamic, but still
527 want to use the template engine to provide headers etc, you can use the
528 auto_page feature to avoid the need to create a route for each page.
529 With "auto_page" enabled, if the requested path does not match any
531 specific route, Dancer2 will check in the views directory for a
532 matching template, and use it to satisfy the request if found.
533 Simply enable auto_page in your config:
535 auto_page: 1
537 Then, if you request "/foo/bar", Dancer2 will look in the views dir for
539 "/foo/bar.tt".
540 Dancer2 will honor your "before_template_render" code, and all default
542 variables. They will be accessible and interpolated on automatic served
543 pages.
544 dsl_class
546 For complex applications that require extended DSL keywords or other
547 functionality the DSL class used can be specified at import time or in
548 the config settings.
549 dsl_class: 'My::DSL'
551 This is the same as specifying
553 use Dancer2 dsl => 'My::DSL'
555 in your module. dsl_class defaults to Dancer2::Core::DSL if not
557 specified
558 Environment variables
560 DANCER_CONFDIR
561 Sets the configuration directory.
563 This correlates to the "confdir" config option.
565 DANCER_ENVDIR
567 Sets the environment directory.
569 This correlates to the "envdir" config option.
571 PLACK_ENV
573 Sets the given environment. This can be overridden by
575 "DANCER_ENVIRONMENT".
576 DANCER_ENVIRONMENT
578 Sets the given environment. This takes higher precedence over
580 "PLACK_ENV".
581 If neither "PLACK_ENV" or "DANCER_ENVIRONMENT" is set, the environment
583 defaults to development.
584 DANCER_APPHANDLER
586 The "DANCER_APPHANDLER" configuration controls what the "dance" keyword
588 does.
589 If is set to "PSGI" (which will automatically be set if "PLACK_ENV" is
591 set), "dance" will return the PSGI application coderef.
592 Otherwise (which is the default is - "Standalone"), it runs the Plack
594 standalone server with the application.
595 DANCER_PORT
597 Sets the port which will be used by the development server (if not run
599 by plackup).
600 DANCER_SERVER
602 Sets the host the development server will be used by the development
604 server (if not run by plackup).
605 Note: this might change in the future.
607 DANCER_STARTUP_INFO
609 Controls whether to display start up info.
611 DANCER_NO_SERVER_TOKENS
613 Controls whether to display the server tokens.
615 DANCER_PUBLIC
617 Sets the public directory location.
619 DANCER_TRACES
621 Sets the tracing flag which sets Carp's $Verbose flag.
623 DANCER_VIEWS
625 Sets the views (templates) directory.
627 DANCER_LOGGER
629 Sets the logger engine.
631 DANCER_CHARSET
633 Sets the default charset.
635 DANCER_CONTENT_TYPE
637 Sets the default content type.
639 If not set, defaults to text/html.
641
643 Dancer2
644
646 Dancer Core Developers
647
649 This software is copyright (c) 2023 by Alexis Sukrieh.
650 This is free software; you can redistribute it and/or modify it under
652 the same terms as the Perl 5 programming language system itself.
653perl v5.38.0 2023-07-20 Dancer2::Config(3)