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

FreeBSD Manual Pages


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

       Dancer::Config -	how to configure Dancer	to suit	your needs

       version 1.3512

       Dancer::Config handles reading and changing the configuration of	your
       Dancer apps.  The documentation for this	module aims to describe	how to
       change settings,	and which settings are available.

       You can change a	setting	with the keyword set, like the following:

	   use Dancer;

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

       A better	way of defining	settings exists: using YAML file. For this to
       be possible, you	have to	install	the YAML module. If a file named
       config.yml exists in the	application directory it will be loaded	as a
       setting group.

       The same	is done	for the	environment file located in the	environments

       To fetch	the available configuration values use the config keyword that
       returns a reference to a	hash:

	   my $port   =	config->{port};
	   my $appdir =	config->{appdir};

       By default, the module YAML will	be used	to parse the configuration
       files.  If desired, it is possible to use YAML::XS instead by changing
       the YAML	engine configuration in	the application	code:

	   config->{engines}{YAML}{module} = 'YAML::XS';

       See Dancer::Serializer::YAML for	more details.

   Run mode and	listening interface/port
       server (string)

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

       Can also	be set with environment	variable DANCER_SERVER

       port (int)

       The port	Dancer will listen to.

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

       Can also	be set with environment	variable DANCER_PORT

       daemon (boolean)

       If set to true, runs the	standalone webserver in	the background.	 This
       setting can be changed on the command-line with the --daemon flag.

       Can also	be enabled by setting environment variable DANCER_DAEMON to a
       true value.

       behind_proxy (boolean)

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

       It will also cause Dancer::Request->address to return what
       Dancer::Request->forwarded_for_address would return, namely the content
       of the `HTTP_X_FORWARDED_FOR` env var/header, so	that requests will
       appear to have come from	the end	user's IP and not the proxy's.

       Because of the above, you should	*not* turn this	on if your app isn't
       behind a	proxy which will pass this information on appropriately,
       otherwise a malicious user could	supply false information.

   Content type	/ character set
       content_type (string)

       The default content type	of outgoing content.  Default value is

       Can also	be set with environment	variable DANCER_CONTENT_TYPE

       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	Dancer in which	charset	the static files and
	   templates are encoded.

       o   If you're using Dancer::Plugin::Database, UTF-8 support will
	   automatically be enabled for	your database -	see "AUTOMATIC UTF-8
	   SUPPORT" in Dancer::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.

       Can also	be set with environment	variable DANCER_CHARSET

       default_mime_type (string)

       Dancer's	Dancer::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

   File	/ directory locations
       environment (string)

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

       The running environment can be set with:

	  set environment => "production";

       Note that this variable is also used as a default value if other	values
       are not defined.

       Can also	be set with environment	variable DANCER_ENVIRONMENT

       appdir (directory)

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

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

       Can also	be set with environment	variable DANCER_APPDIR

       public (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

       By default it points to $appdir/public.

       views (directory)

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

       This defaults to	$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. Dancer 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 "Dancer" manpage for details.

   Logging, debugging and error	handling
       strict_config (boolean, default:	false)

       If true,	"config" will return an	object instead of a hash reference.
       See Dancer::Config::Object for more information.

       global_warnings (boolean, default: false)

       If true,	"use warnings" will be in effect for all modules and scripts
       loaded by your Dancer application. Default is false.

       Can also	be enabled by setting the environment variable DANCER_WARNINGS
       to a true value.

       startup_info (boolean)

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

       Can also	be disabled by setting the environment variable
       DANCER_NO_STARTUP_INFO to a true	value.

       warnings	(boolean)

       If set to true, tells Dancer to consider	all warnings as	blocking
       errors. Default is false.

       traces (boolean)

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

       Can also	be enabled by setting environment variable DANCER_TRACES to a
       true value.

       require_environment (boolean)

       If set to true, Dancer will fail	during startup if your environment
       file is missing or can't	be read. This is especially useful in
       production when you have	things like memcached settings that need to be
       set per-environment.  Defaults to false.

       server_tokens (boolean)

       If set to true (the default), Dancer will add an	"X-Powered-By" header
       and also	append the Dancer version to the "Server" header.

       Can also	be disabled by setting the environment variable
       DANCER_NO_SERVER_TOKENS to a true value.

       log_path	(string)

       Folder where the	``file "logger"'' saves	log files.

       log_file	(string)

       Name of the file	to create when ``file "logger"'' is active. It
       defaults	to the "environment" setting contents.

       logger (enum)

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

	   logger: file

       Or to direct log	messages to the	console	from which you started your
       Dancer app in standalone	mode,

	   logger: console

       Various other logger backends are available on CPAN, including
       Dancer::Logger::Syslog, Dancer::Logger::Log4perl, Dancer::Logger::PSGI
       (which can, with	the aid	of Plack middlewares, send log messages	to a
       browser's console window) and others.

       Can also	be set with environment	variable DANCER_LOGGER

       log (enum)

       Tells which log messages	should be actually logged. Possible values are
       core, debug, warning or error.

       core : all messages are logged, including some from Dancer 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 Dancer is doing.  In
       production, you'll likely want "error" or "warning" only, for less-
       chatty logs.

       show_errors (boolean)

       If set to true, Dancer will render a detailed debug screen whenever an
       error is	caught.	If set to false, Dancer	will render the	default	error
       page, using $public/$error_code.html if it exists 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 can use three variables:

	   The error title.

	   The error message.

	   The code throwing that error.

   Session engine
       session (enum)

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

       See Dancer::Session for supported engines and their respective


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


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


       The user's session ID is	stored in a cookie.  If	the "session_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 its value.


       Allows you to set the domain property on	the cookie, which will
       override	the default.  This is useful for setting the session cookie's
       domain to something like	"" so that the same cookie will be
       applicable and usable across subdomains of a base domain.

   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, Dancer 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",	Dancer will look in the	views dir for

       Dancer will honor your "before_template_render" code, and all default
       variables. They will be accessible and interpolated on automaticly-
       served pages.

       The pages served	this way will have "Content-Type" set to "text/html",
       so don't	use the	feature	for anything else.

   Route caching
       route_cache (boolean)

       If true,	enables	route caching (for quicker route resolution on larger
       apps - not caching of responses).  See Dancer::Route::Cache for
       details.	Default	is false.

       route_cache_size_limit (bytes)

       Maximum size of route cache (e.g. 1024, 2M). Defaults to	10M (10MB) -
       see Dancer::Route::Cache

       route_cache_path_limit (number)

       Maximum number of routes	to cache. Defaults to 600 - see

       It's possible to	set the	configuration directory	and environment
       directory using these two environment variables.	Setting
       `DANCER_CONFDIR`	will have the same effect as doing

	   set confdir => '/path/to/confdir'

       and setting `DANCER_ENVDIR` will	be similar to:

	   set envdir => '/path/to/environments'

       Some settings can be provided via environment variables at runtime, as
       detailed	above; a full list of environment variables you	can use


       DANCER_APPHANDLER a Dancer::Handler::* by default















       This module has been written by Alexis Sukrieh <>	and
       others, see the AUTHORS file that comes with this distribution for

       This module is free software and	is released under the same terms as
       Perl itself.


       Dancer Core Developers

       This software is	copyright (c) 2010 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			  2019-03-31		     Dancer::Config(3)


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

home | help