Dancer2::Config - Configure Dancer2 to suit your needs

Author

       Dancer Core Developers

Copyright And License

       This software is copyright (c) 2024 by Alexis Sukrieh.

       This is free software; you can redistribute it and/or modify it under  the  same  terms  as  the  Perl  5
       programming language system itself.

perl v5.40.0                                       2024-12-08                               Dancer2::Config(3pm)

Description

       The Dancer2 configuration (as implemented by Dancer2::Core::Role::ConfigReader) handles reading and
       changing the configuration of your Dancer2 apps.  This document describes how to manipulate Dancer2's
       configuration settings (through code or by file), and to document the various settings that are available
       in Dancer2.

Manipulating Settings Via Code

       You can change a setting with the keyword "set":

           use Dancer2;

           # changing default settings
           set port         => 8080;
           set content_type => 'text/plain';
           set startup_info => 0;

Manipulating Settings Via Configuration Files

There's nothing wrong with using "set" to configure your application. In fact you might have some great
reasons for doing so. For greater flexibility, ease of deployment, etc., you should also consider
extracting those settings into a configuration file.

Configurationfilepathandfilenames
Dancer2 will first look for the file config.EXT (where EXT is the type of configuration file you are
using; e.g. ini or json or yml) in the root directory of your application. This is considered your global
Dancer2 config file. If you do not care to have separate settings for production and development
environments (not a recommended practice!), then this file is all you need.

Next, Dancer2 will look for a file called config_local.EXT. This file is typically useful for deployment-
specific configuration that should not be checked into source control. For instance, database credentials
could be stored in this file. Any settings in this file are merged into the existing configuration such
that those with the same name in your local configuration file will take precedence over those settings
in the global file.

Next, Dancer2 will look in the environments directory for a configuration file specific to the platform
you are deploying to (production.EXT or development.EXT, for example). Again, the configuration from the
environment is merged with the existing configuration with the deployment config taking precedence.

Finally, Dancer2 will look in the environments directory for a local configuration for the specific
platform you are deploying to (e.g. production_local.EXT or development_local.EXT) The configuration in
this file is merged as before.

Much like config_local.EXT, this file would be useful for environment- specific configuration that would
not be checked into source control. For instance, when developing an application that talks to multiple
services, each developer could have their own URLs to those services stored within their
environments/development_local.yaml file.

Note, if there is no config.EXT, Dancer2 will not look for a config_local.EXT. The same is true for the
local environment configuration.

Supportedconfigurationfileformats
Dancer2 supports any configuration file format that is supported by Config::Any. At the time of this
writing, that includes YAML (.yml and .yaml), JSON (.jsn and .json), INI (.ini), Apache-style
configurations (.cnf and .conf), XML (.xml), and Perl-style hashes (.pl and .perl).

Dancer2 iterates over these file extensions in the order provided by Config::Any and loads any config
files that it finds with later configuration information overriding earlier config information. To
restrict which file extension Dancer2 looks for, you may set the "DANCER_CONFIG_EXT" envinroment variable
to a specific extension and Dancer2 will only look for config files with that extension.

Make sure you pick the appropriate extension for your configuration file name, as Dancer2 guesses the
type of format based on the file extension.

Sampleconfigurationfiles
Note: Not all possibilities are covered here, only the most common options.

If you prefer YAML, a sample YAML based config file might look like this:

appname: "Hello"
charset: "UTF-8"
auto_page: 1

session: "YAML"
serializer: "JSON"

plugins:
DBIC:
default:
dsn: dbi:SQLite:db/mydata.db
schema_class: Hello::Schema

If JSON is more your thing, your file might look more like this:

{
"appname": "Hello",
"charset": "UTF-8",
"auto_page": "1",
"session": "YAML",
"serializer": "JSON",
"plugins": {
"DBIC": {
"default": {
"dsn": "dbi:SQLite:db/mydata.db",
"schema_class": "Hello::Schema"
}
}
}
}

If you like Apache configuration files, try something similar to:

appname = Hello
charset = UTF-8
auto_page = 1
session = YAML
serializer = JSON
<plugins>
<DBIC>
<default>
dsn = dbi =SQLite =db/mydata.db
schema_class = Hello = =Schema
</default>
</DBIC>
</plugins>

INI-style files are deliberately simplistic and not recommended for use in your Dancer2 applications.

Name

       Dancer2::Config - Configure Dancer2 to suit your needs

Supported Settings

Runmodeandlisteninginterface/porthost(string)

The IP address that the Dancer2 app should bind to. Default is 0.0.0.0, i.e. bind to all available
interfaces.

port(int)

The port Dancer2 will listen to.

Default value is 3000. This setting can be changed on the command-line with the --port switch.

behind_proxy(boolean)

If set to true, Dancer2 will look to "X-Forwarded-Protocol" and "X-Forwarded-host" when constructing URLs
(for example, when using "redirect" or "host"). This is useful if your application is behind a proxy.

Note: If either of these are missing, the values of the proxy server will be used instead. For example,
if the client sends a HTTP/1.0 request to a proxy that is hosted locally, then "host" will return the
value "localhost". In a similar vein, if the client makes a secure connection to the proxy, but the proxy
does not pass "X-Forwarded-Protocol", then "base" will return "http://...". For these reasons, it is
recommended that the values are hard-configured in the proxy if possible. For Apache this would be:

RequestHeader set X_FORWARDED_PROTO "https"
RequestHeader set X_FORWARDED_HOST "www.example.com"

no_default_middleware(boolean)

If set to true, your Dancer2 application will NOT be wrapped with the default PSGI middleware. The
default middleware wrappers are:

• Plack::Middleware::FixMissingBodyInRedirect

• Plack::Middleware::Head

Contenttype/charactersetcontent_type(string)

The default content type of outgoing content. Default value is 'text/html'.

charset(string)

This setting has multiple effects:

• It sets the default charset of outgoing content. "charset=" item will be added to Content-Type
response header.

• It makes Unicode bodies in HTTP responses of "text/*" types to be encoded to this charset.

• It also indicates to Dancer2 in which charset the static files and templates are encoded.

• If you're using Dancer2::Plugin::Database, UTF-8 support will automatically be enabled for your
database - see "AUTOMATIC UTF-8 SUPPORT" in Dancer2::Plugin::Database

Default value is empty which means don't do anything. HTTP responses without charset will be interpreted
as ISO-8859-1 by most clients.

You can cancel any charset processing by specifying your own charset in Content-Type header or by
ensuring that response body leaves your handler without Unicode flag set (by encoding it into some 8bit
charset, for example).

Also, since automatically serialized JSON responses have "application/json" Content-Type, you should
always encode them by hand.

default_mime_type(string)

Dancer2's Dancer2::Core::MIME module uses "application/data" as a default mime type. This setting lets
the user change it. For example, if you have a lot of files being served in the public folder that do not
have an extension, and are text files, set the "default_mime_type" to "text/plain".

Serializingresponsesserializer(string)

When writing a webservice, data serialization/deserialization is a common issue to deal with. Dancer2 can
automatically handle that for you, via a serializer.

Availableserializerengines

The following serializers are available, be aware they dynamically depend on Perl modules you may not
have on your system.

• JSON

Requires JSON.

• YAML

Requires YAML,

• XML

Requires XML::Simple.

• Mutable

Will try to find the appropriate serializer using the Content-Type and Accept-type header of the
request.

Serializerengine
The serializer can be configured in a separate "engines" section, like so:

serializer: "JSON"

engines:
serializer:
JSON:
pretty: 1

See documentation for a particular serializer for supported options.

File/directorylocationsenvironment(string)

This is the name of the environment that should be used. Standard Dancer2 applications have a
"environments" folder with specific configuration files for different environments (usually development
and production environments). They specify different kind of error reporting, deployment details, etc.
These files are read after the generic "config.yml" configuration file.

appdir(directory)

This is the path where your application will live. It's where Dancer2 will look by default for your
config files, templates and static content.

It is typically set by "use Dancer2" to use the same directory as your script.

public_dir(directory)

This is the directory, where static files are stored. Any existing file in that directory will be served
as a static file, before matching any route.

Version

       version 1.1.2