Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Dancer2::Config(3)    User Contributed Perl Documentation   Dancer2::Config(3)

       Dancer2::Config - Configure Dancer2 to suit your	needs

       version 0.300004

       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.

       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;

       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.

   Configuration file path and file names
       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

   Supported configuration file	formats
       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

   Sample configuration	files
       Note: Not all possibilities are covered here, only the most common

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

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

	   session: "YAML"
	   serializer: "JSON"

		 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
			   dsn = dbi =SQLite =db/mydata.db
			   schema_class	= Hello	= =Schema

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

   Run mode and	listening interface/port
       host (string)

       The IP address that the Dancer2 app should bind to.  Default is,	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

       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 ""

       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:

       o   Plack::Middleware::FixMissingBodyInRedirect

       o   Plack::Middleware::Head

   Content type	/ character set
       content_type (string)

       The default content type	of outgoing content.  Default value is

       charset (string)

       This setting has	multiple effects:

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

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

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

       o   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".

   Serializing responses
       serializer (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.

       Available serializer engines

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

       o   JSON

	   Requires JSON.

       o   YAML

	   Requires YAML,

       o   XML

	   Requires XML::Simple.

       o   Mutable

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

   Serializer engine
       The serializer can be configured	in a separate "engines"	section, like

	  serializer: "JSON"

		pretty:	1

       See documentation for a particular serializer for supported options.

   File	/ directory locations
       environment (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

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

       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

       See also	static_handler.

       Default:	"$appdir/public".

       static_handler (boolean)

       This setting have to be declared	and set	to true	if you modify standard
       "public_dir" location.

       Default:	true if	$ENV{DANCER_PUBLIC} is set or "public_dir" is set to

       views (directory)

       This is the directory where your	templates and layouts live.  It's the
       "view" part of MVC (model, view,	controller).

       Default:	"$appdir/views".

   Templating &	layouts

       Allows you to configure which template engine should be used.  For
       instance, to use	Template Toolkit, add the following to "config.yml":

	   template: template_toolkit

       layout (string)

       The name	of the layout to use when rendering view. Dancer2 will look
       for a matching template in the directory	"$views/layouts".

       Your can	override the default layout using the third argument of	the
       "template" keyword. Check "Dancer2" manpage for details.

       layout_dir (string)

       A relative path where the layouts reside	inside the "views" directory.

	   layout_dir: actual_layouts

       Default:	layouts.

   Logging, debugging and error	handling
       startup_info (boolean)

       If set to true, prints a	banner at the server start with	information
       such as versions	and the	environment (or	"dancefloor").

       Conforms	to the environment variable "DANCER_STARTUP_INFO".

       traces (boolean)

       If set to true, Dancer2 will display full stack traces when a warning
       or a die	occurs.	(Internally sets Carp::Verbose). Default to false.

       no_server_tokens	(boolean)

       If set to true, Dancer2 will not	add an "X-Powered-By" header and also
       append the Dancer2 version to the "Server" header. Default to false -

       You can also use	the environment	variable "DANCER_NO_SERVER_TOKENS".

       logger (enum)

       Select which logger to use.  For	example, to write to log files with

	   logger: File

       Or to direct log	messages to the	console	from which you started your
       Dancer2 app with	Dancer2::Logger::Console:

	   logger: Console

       Loggers are configured with a corresponding "Logger engine" section, as
       shown below.

       session (enum)

       This setting lets you enable a session engine for your web application.
       By default, sessions are	disabled in Dancer2, you must choose a session
       engine to use them.

       Sessions	are configured with a corresponding "Session engine" section,
       as shown	below.

       show_errors (boolean)

       If set to true, Dancer2 will render a detailed debug screen whenever an
       error is	caught.	If set to false, Dancer2 will render the default error
       page, using "$public/$error_code.html" if it exists,
       "$views/$" or the template specified by the
       "error_template"	setting.

       The error screen	attempts to sanitise sensitive looking information
       (passwords / card numbers in the	request, etc) but you still should not
       have show_errors	enabled	whilst in production, as there is still	a risk
       of divulging details.

       error_template (template	path)

       This setting lets you specify a template	to be used in case of runtime
       error. At the present moment the	template (as well as
       "$views/$" templates) can use four variables:

	   The error title.

	   The error specific content (if any).

	   The HTTP status code	throwing that error.

	   The stringified exception (e.g. $@) if any.

       Keep in mind that 'content' and 'exception' can vary depending on the

       For example:

       A 404 has an empty 'exception' and 'content' contains the URI that was
       not found. Unless you do	the 404	yourself via  "send_error("You chose
       ... poorly!", 404);", then 'content' is 'You chose ... poorly!'.

       A 500 because of, say, dividing 0 by 0 will have	an empty 'content' and
       'exception like 'Illegal	division by zero at ...'.

       A 401 from "send_error("You can not know	the secret until you sign in
       grasshopper!", 401);" will have an empty	'exception' and	'content' will
       contain 'You can	not know the secret until you sign in grasshopper!'.

   Logger engine
       The logger must be configured in	a separate "engines" section, like so:

	  logger: Console

		log_level: core

       All loggers support the configuration options below.  See documentation
       for a particular	logger for other supported options.


       This option tells which log messages should be actually logged.
       Possible	values are core, info, debug, warning or error.

       core : all messages are logged, including some from Dancer2 itself
       debug : all messages are	logged
       info : only info, warning and error messages are	logged
       warning : only warning and error	messages are logged
       error : only error messages are logged

       During development, you'll probably want	to use "debug" to see your own
       debug messages, and "core" if you need to see what Dancer2 is doing.
       In production, you'll likely want "error" or "warning" only, for	less-
       chatty logs.

   Session engine
       The session engine is configured	in the "engines" section.

	  session: Simple

		cookie_name: dance.set
		cookie_duration: '24 hours'
		cookie_same_site: Lax
		is_secure: 1
		is_http_only: 1

       See Dancer2::Core::Role::SessionFactory for more	detailed documentation
       for these options, or the particular session engine for other supported


       The name	of the cookie to store the session ID in.  Defaults to
       "dancer.session".  This can be overridden by certain session engines.


       The domain of the cookie. By default there is no	domain defined for the


       The path	of the cookie. By default there	is no path defined for the


       The session expiry time in seconds, or as e.g. "2 hours"	(see "expires"
       in Dancer2::Core::Cookie.  By default, there is no specific expiry


       The user's session ID is	stored in a cookie.  If	the "is_secure"
       setting is set to a true	value, the cookie will be marked as secure,
       meaning it should only be sent over HTTPS connections.


       This setting defaults to	1 and instructs	the session cookie to be
       created with the	"HttpOnly" option active, meaning that JavaScript will
       not be able to access to	its value.

       Restricts the session cookie to a first-party or	same-site context.
       Valid values are	"Strict", "Lax", or "None".

       Refer to	RFC6265bis <
       cookie-same-site> for further details regarding same-site context.

   auto_page (boolean)
       For simple pages	where you're not doing anything	dynamic, but still
       want to use the template	engine to provide headers etc, you can use the
       auto_page feature to avoid the need to create a route for each page.

       With "auto_page"	enabled, if the	requested path does not	match any
       specific	route, Dancer2 will check in the views directory for a
       matching	template, and use it to	satisfy	the request if found.

       Simply enable auto_page in your config:

	   auto_page: 1

       Then, if	you request "/foo/bar",	Dancer2	will look in the views dir for

       Dancer2 will honor your "before_template_render"	code, and all default
       variables. They will be accessible and interpolated on automatic	served

       For complex applications	that require extended DSL keywords or other
       functionality the DSL class used	can be specified at import time	or in
       the config settings.

	   dsl_class: 'My::DSL'

       This is the same	as specifying

	   use Dancer2 dsl => 'My::DSL'

       in your module. dsl_class defaults to Dancer2::Core::DSL	if not

   Environment variables

       Sets the	configuration directory.

       This correlates to the "confdir"	config option.


       Sets the	environment directory.

       This correlates to the "envdir" config option.


       Sets the	given environment. This	can be overridden by


       Sets the	given environment. This	takes higher precedence	over

       If neither "PLACK_ENV" or "DANCER_ENVIRONMENT" is set, the environment
       defaults	to development.


       The "DANCER_APPHANDLER" configuration controls what the "dance" keyword

       If is set to "PSGI" (which will automatically be	set if "PLACK_ENV" is
       set), "dance" will return the PSGI application coderef.

       Otherwise (which	is the default is - "Standalone"), it runs the Plack
       standalone server with the application.


       Sets the	port which will	be used	by the development server (if not run
       by plackup).


       Sets the	host the development server will be used by the	development
       server (if not run by plackup).

       Note: this might	change in the future.


       Controls	whether	to display start up info.


       Controls	whether	to display the server tokens.


       Sets the	public directory location.


       Sets the	tracing	flag which sets	Carp's $Verbose	flag.


       Sets the	views (templates) directory.


       Sets the	logger engine.


       Sets the	default	charset.


       Sets the	default	content	type.

       If not set, defaults to text/html.


       Dancer Core Developers

       This software is	copyright (c) 2020 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.32.0			  2020-05-27		    Dancer2::Config(3)


Want to link to this manual page? Use this URL:

home | help