1Dancer2::Config(3)    User Contributed Perl Documentation   Dancer2::Config(3)
2
3
4

NAME

6       Dancer2::Config - Configure Dancer2 to suit your needs
7

VERSION

9       version 0.300005
10

DESCRIPTION

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

MANIPULATING SETTINGS VIA CODE

19       You can change a setting with the keyword "set":
20
21           use Dancer2;
22
23           # changing default settings
24           set port         => 8080;
25           set content_type => 'text/plain';
26           set startup_info => 0;
27

MANIPULATING SETTINGS VIA CONFIGURATION FILES

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
34   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
42       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
50       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
56       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
61       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
67       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
71   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
77       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
84       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
88   Sample configuration files
89       Note: Not all possibilities are covered here, only the most common
90       options.
91
92       If you prefer YAML, a sample YAML based config file might look like
93       this:
94
95           appname: "Hello"
96           charset: "UTF-8"
97           auto_page: 1
98
99           session: "YAML"
100           serializer: "JSON"
101
102           plugins:
103             DBIC:
104               default:
105                 dsn: dbi:SQLite:db/mydata.db
106                 schema_class: Hello::Schema
107
108       If JSON is more your thing, your file might look more like this:
109
110           {
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
126       If you like Apache configuration files, try something similar to:
127
128               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
142       INI-style files are deliberately simplistic and not recommended for use
143       in your Dancer2 applications.
144

SUPPORTED SETTINGS

146   Run mode and listening interface/port
147       host (string)
148
149       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
152       port (int)
153
154       The port Dancer2 will listen to.
155
156       Default value is 3000. This setting can be changed on the command-line
157       with the --port switch.
158
159       behind_proxy (boolean)
160
161       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
166       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
175           RequestHeader set X_FORWARDED_PROTO "https"
176           RequestHeader set X_FORWARDED_HOST "www.example.com"
177
178       no_default_middleware (boolean)
179
180       If set to true, your Dancer2 application will NOT be wrapped with the
181       default PSGI middleware. The default middleware wrappers are:
182
183       •   Plack::Middleware::FixMissingBodyInRedirect
184
185       •   Plack::Middleware::Head
186
187   Content type / character set
188       content_type (string)
189
190       The default content type of outgoing content.  Default value is
191       'text/html'.
192
193       charset (string)
194
195       This setting has multiple effects:
196
197       •   It sets the default charset of outgoing content. "charset=" item
198           will be added to Content-Type response header.
199
200       •   It makes Unicode bodies in HTTP responses of "text/*" types to be
201           encoded to this charset.
202
203       •   It also indicates to Dancer2 in which charset the static files and
204           templates are encoded.
205
206       •   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
210       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
213       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
218       Also, since automatically serialized JSON responses have
219       "application/json" Content-Type, you should always encode them by hand.
220
221       default_mime_type (string)
222
223       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
229   Serializing responses
230       serializer (string)
231
232       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
236       Available serializer engines
237
238       The following serializers are available, be aware they dynamically
239       depend on Perl modules you may not have on your system.
240
241JSON
242
243           Requires JSON.
244
245YAML
246
247           Requires YAML,
248
249XML
250
251           Requires XML::Simple.
252
253Mutable
254
255           Will try to find the appropriate serializer using the Content-Type
256           and Accept-type header of the request.
257
258   Serializer engine
259       The serializer can be configured in a separate "engines" section, like
260       so:
261
262          serializer: "JSON"
263
264          engines:
265            serializer:
266              JSON:
267                pretty: 1
268
269       See documentation for a particular serializer for supported options.
270
271   File / directory locations
272       environment (string)
273
274       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
281       appdir (directory)
282
283       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
287       It is typically set by "use Dancer2" to use the same directory as your
288       script.
289
290       public_dir (directory)
291
292       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
296       See also static_handler.
297
298       Default: "$appdir/public".
299
300       static_handler (boolean)
301
302       This setting have to be declared and set to true if you modify standard
303       "public_dir" location.
304
305       Default: true if $ENV{DANCER_PUBLIC} is set or "public_dir" is set to
306       "$appdir/public".
307
308       views (directory)
309
310       This is the directory where your templates and layouts live.  It's the
311       "view" part of MVC (model, view, controller).
312
313       Default: "$appdir/views".
314
315   Templating & layouts
316       template
317
318       Allows you to configure which template engine should be used.  For
319       instance, to use Template Toolkit, add the following to "config.yml":
320
321           template: template_toolkit
322
323       layout (string)
324
325       The name of the layout to use when rendering view. Dancer2 will look
326       for a matching template in the directory "$views/layouts".
327
328       Your can override the default layout using the third argument of the
329       "template" keyword. Check "Dancer2" manpage for details.
330
331       layout_dir (string)
332
333       A relative path where the layouts reside inside the "views" directory.
334
335           layout_dir: actual_layouts
336
337       Default: layouts.
338
339   Logging, debugging and error handling
340       startup_info (boolean)
341
342       If set to true, prints a banner at the server start with information
343       such as versions and the environment (or "dancefloor").
344
345       Conforms to the environment variable "DANCER_STARTUP_INFO".
346
347       traces (boolean)
348
349       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
352       no_server_tokens (boolean)
353
354       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
358       You can also use the environment variable "DANCER_NO_SERVER_TOKENS".
359
360       logger (enum)
361
362       Select which logger to use.  For example, to write to log files with
363       Dancer2::Logger::File:
364
365           logger: File
366
367       Or to direct log messages to the console from which you started your
368       Dancer2 app with Dancer2::Logger::Console:
369
370           logger: Console
371
372       Loggers are configured with a corresponding "Logger engine" section, as
373       shown below.
374
375       session (enum)
376
377       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
381       Sessions are configured with a corresponding "Session engine" section,
382       as shown below.
383
384       show_errors (boolean)
385
386       If set to true, Dancer2 will render a detailed debug screen whenever an
387       error is caught. If set to false, Dancer2 will render the default error
388       page, using "$public/$error_code.html" if it exists,
389       "$views/$error_code.tt" or the template specified by the
390       "error_template" setting.
391
392       The error screen attempts to sanitise sensitive looking information
393       (passwords / card numbers in the request, etc) but you still should not
394       have show_errors enabled whilst in production, as there is still a risk
395       of divulging details.
396
397       error_template (template path)
398
399       This setting lets you specify a template to be used in case of runtime
400       error. At the present moment the template (as well as
401       "$views/$error_code.tt" templates) can use four variables:
402
403       title
404           The error title.
405
406       content
407           The error specific content (if any).
408
409       status
410           The HTTP status code throwing that error.
411
412       exception
413           The stringified exception (e.g. $@) if any.
414
415       Keep in mind that 'content' and 'exception' can vary depending on the
416       problem.
417
418       For example:
419
420       A 404 has an empty 'exception' and 'content' contains the URI that was
421       not found. Unless you do the 404 yourself via  "send_error("You chose
422       ... poorly!", 404);", then 'content' is 'You chose ... poorly!'.
423
424       A 500 because of, say, dividing 0 by 0 will have an empty 'content' and
425       'exception like 'Illegal division by zero at ...'.
426
427       A 401 from "send_error("You can not know the secret until you sign in
428       grasshopper!", 401);" will have an empty 'exception' and 'content' will
429       contain 'You can not know the secret until you sign in grasshopper!'.
430
431   Logger engine
432       The logger must be configured in a separate "engines" section, like so:
433
434          logger: Console
435
436          engines:
437            logger:
438              Console:
439                log_level: core
440
441       All loggers support the configuration options below.  See documentation
442       for a particular logger for other supported options.
443
444       log_level
445
446       This option tells which log messages should be actually logged.
447       Possible values are core, info, debug, warning or error.
448
449       core : all messages are logged, including some from Dancer2 itself
450       debug : all messages are logged
451       info : only info, warning and error messages are logged
452       warning : only warning and error messages are logged
453       error : only error messages are logged
454
455       During development, you'll probably want to use "debug" to see your own
456       debug messages, and "core" if you need to see what Dancer2 is doing.
457       In production, you'll likely want "error" or "warning" only, for less-
458       chatty logs.
459
460   Session engine
461       The session engine is configured in the "engines" section.
462
463          session: Simple
464
465          engines:
466            session:
467              Simple:
468                cookie_name: dance.set
469                cookie_duration: '24 hours'
470                cookie_same_site: Lax
471                is_secure: 1
472                is_http_only: 1
473
474       See Dancer2::Core::Role::SessionFactory for more detailed documentation
475       for these options, or the particular session engine for other supported
476       options.
477
478       cookie_name
479
480       The name of the cookie to store the session ID in.  Defaults to
481       "dancer.session".  This can be overridden by certain session engines.
482
483       cookie_domain
484
485       The domain of the cookie. By default there is no domain defined for the
486       cookie.
487
488       cookie_path
489
490       The path of the cookie. By default there is no path defined for the
491       cookie.
492
493       cookie_duration
494
495       The session expiry time in seconds, or as e.g. "2 hours" (see "expires"
496       in Dancer2::Core::Cookie.  By default, there is no specific expiry
497       time.
498
499       cookie_same_site
500
501       Restricts the session cookie to a first-party or same-site context.
502       Valid values are "Strict", "Lax", or "None".
503
504       Refer to RFC6265bis <https://tools.ietf.org/html/draft-ietf-httpbis-
505       cookie-same-site> for further details regarding same-site context.
506
507       is_secure
508
509       The user's session ID is stored in a cookie.  If the "is_secure"
510       setting is set to a true value, the cookie will be marked as secure,
511       meaning it should only be sent over HTTPS connections.
512
513       is_http_only
514
515       This setting defaults to 1 and instructs the session cookie to be
516       created with the "HttpOnly" option active, meaning that JavaScript will
517       not be able to access to its value.
518
519   auto_page (boolean)
520       For simple pages where you're not doing anything dynamic, but still
521       want to use the template engine to provide headers etc, you can use the
522       auto_page feature to avoid the need to create a route for each page.
523
524       With "auto_page" enabled, if the requested path does not match any
525       specific route, Dancer2 will check in the views directory for a
526       matching template, and use it to satisfy the request if found.
527
528       Simply enable auto_page in your config:
529
530           auto_page: 1
531
532       Then, if you request "/foo/bar", Dancer2 will look in the views dir for
533       "/foo/bar.tt".
534
535       Dancer2 will honor your "before_template_render" code, and all default
536       variables. They will be accessible and interpolated on automatic served
537       pages.
538
539   dsl_class
540       For complex applications that require extended DSL keywords or other
541       functionality the DSL class used can be specified at import time or in
542       the config settings.
543
544           dsl_class: 'My::DSL'
545
546       This is the same as specifying
547
548           use Dancer2 dsl => 'My::DSL'
549
550       in your module. dsl_class defaults to Dancer2::Core::DSL if not
551       specified
552
553   Environment variables
554       DANCER_CONFDIR
555
556       Sets the configuration directory.
557
558       This correlates to the "confdir" config option.
559
560       DANCER_ENVDIR
561
562       Sets the environment directory.
563
564       This correlates to the "envdir" config option.
565
566       PLACK_ENV
567
568       Sets the given environment. This can be overridden by
569       "DANCER_ENVIRONMENT".
570
571       DANCER_ENVIRONMENT
572
573       Sets the given environment. This takes higher precedence over
574       "PLACK_ENV".
575
576       If neither "PLACK_ENV" or "DANCER_ENVIRONMENT" is set, the environment
577       defaults to development.
578
579       DANCER_APPHANDLER
580
581       The "DANCER_APPHANDLER" configuration controls what the "dance" keyword
582       does.
583
584       If is set to "PSGI" (which will automatically be set if "PLACK_ENV" is
585       set), "dance" will return the PSGI application coderef.
586
587       Otherwise (which is the default is - "Standalone"), it runs the Plack
588       standalone server with the application.
589
590       DANCER_PORT
591
592       Sets the port which will be used by the development server (if not run
593       by plackup).
594
595       DANCER_SERVER
596
597       Sets the host the development server will be used by the development
598       server (if not run by plackup).
599
600       Note: this might change in the future.
601
602       DANCER_STARTUP_INFO
603
604       Controls whether to display start up info.
605
606       DANCER_NO_SERVER_TOKENS
607
608       Controls whether to display the server tokens.
609
610       DANCER_PUBLIC
611
612       Sets the public directory location.
613
614       DANCER_TRACES
615
616       Sets the tracing flag which sets Carp's $Verbose flag.
617
618       DANCER_VIEWS
619
620       Sets the views (templates) directory.
621
622       DANCER_LOGGER
623
624       Sets the logger engine.
625
626       DANCER_CHARSET
627
628       Sets the default charset.
629
630       DANCER_CONTENT_TYPE
631
632       Sets the default content type.
633
634       If not set, defaults to text/html.
635

SEE ALSO

637       Dancer2
638

AUTHOR

640       Dancer Core Developers
641
643       This software is copyright (c) 2021 by Alexis Sukrieh.
644
645       This is free software; you can redistribute it and/or modify it under
646       the same terms as the Perl 5 programming language system itself.
647
648
649
650perl v5.32.1                      2021-01-31                Dancer2::Config(3)
Impressum