Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

923 lines (421 sloc) 23.707 kb

Configuration parameters

Configure your Play application by setting values for configuration keys in conf/application.conf file. See also:

Application configuration

h3(#application.baseUrl). application.baseUrl

The application base URL used for reverse-resolving absolute URLs. This is used by the @@{..} template syntax and in Jobs, which do not have an inbound Http.Request), such as rendering e-mail. For example, for dev mode:


For prod mode:


h3(#application.defaultCookieDomain). application.defaultCookieDomain

Enables session/cookie sharing between subdomains. For example, to make cookies valid for all domains ending with ‘’, e.g. and

Default: a cookie is only valid for a specific domain.

h3(#application.lang.cookie). application.lang.cookie

The name of the cookie that is used to store the current language, set by play.i18n.Lang.change(String locale), which you can change if you want separate language settings for separate Play applications. For example:


Default: PLAY_LANG

h3(#application.langs). application.langs

Defines locales used by your application. You can then place localised messages in conf/messages.{locale} files. The value is a comma-separated list of language codes, for example:


Default: no additional languages.

h3(#application.log). application.log

Specifies log level for your application. For example:


Default: INFO

See also: Logging configuration.

h3(#application.log.path). application.log.path

Path to a Log4J configuration file, to customise log output. If you do not specify a path, Play will load a file in the conf directory if present.


Default: /log4j.xml falling back to /

h3(#application.log.recordCaller). application.log.recordCaller

Configures the value of play.Logger.recordCaller to record and display the caller method. For example:


Default: false

h3(#application.mode). application.mode

Application mode (case insensitive). For example:



  • DEV – enable instant reloading and other development help
  • PROD – pre-compiles and caches Java sources and templates.

Default: DEV


The application’s name, usually set by the play new command.

Default: no value.

h3(#application.secret). application.secret

The secret key is used to secure cryptographic functions, usually set by the play new or play secret command. If you deploy your application to several instances be sure to use the same key. For example:


If not set, play.libs.Crypto.sign will not encrypt messages; in particular, sessions will not be encrypted.

Default: no value.

h3(#application.session.cookie). application.session.cookie

Session cookie name. The cookies are not secured by default, only set it to true if you’re serving your pages through HTTPS. For example:


Default: sessions are written to the transient PLAY_SESSION cookie.

h3(#application.session.httpOnly). application.session.httpOnly

Enables the ‘HTTP only’ flag on cookies, which mitigates some XSS attacks. For example:


Default: false

For more information see the OWASP page on HttpOnly.

h3(#application.session.maxAge). application.session.maxAge

Session time-out, i.e. the maximum age of the session cookie. If not set, the session expires when you close your web browser. For example, to set the session to one hour:


Remember the session for one week:


Default: the session is based on a transient cookie expires when the browser is closed.


Enables Cookie-based sessions for HTTPS connections. For example:

Default: false

h3(#application.session.sendOnlyIfChanged). application.session.sendOnlyIfChanged

Avoid sending the session cookie if there were no changes to the session. For example:


Default: false

h3(#application.web_encoding). application.web_encoding

The text encoding that Play uses when communicating with the web browser and for the Web Service client. You do not normally need to set this, since Play defaults to using UTF-8. For example:


Default: UTF-8

Changing application.web_encoding affects the charset part of the Content-type HTTP header. It also affects which encoding is used when transmitting rendered dynamic results, but it does not affect the bytes sent when Play serves static content: So, if you have modified the default response encoding and you have static text-files (in the public/ folder) that contain special characters, you must make sure that these files are stored according to the specified encoding. All other files should be stored in UTF-8.


h3(#attachments.path). attachments.path

Storage path for play.db.jpa.Blob content. This can be an absolute path, or a relative path to a folder inside the Play application folder. For example:


Default: attachments

X509 certificates

h3(#certificate.key.file). certificate.key.file

Specifies an X509 certificate key, for HTTPS support. The file must be named host.key. For example:


Default: conf/host.key

h3(#certificate.file). certificate.file

Specifies an X509 certificate file, for HTTPS support. The file must be named host.cert. For example:


Default: conf/host.cert

h3(#certificate.password). certificate.password

Password for a password-protected X509 certificate key file, for use with the certificate.key.file configuration. For example:


Default: secret

Scheduled jobs

You can configure cron expressions for scheduled jobs as configuration keys that start with cron. and use the key as the value of a or @Every annotation. For example, @On("cron.noon") refers to:

cron.noon=0 0 12 * * ?

Date formats

h3(#date.format). date.format

Sets the default date format, using a java.text.SimpleDateFormat pattern. For example:


This property also affects how ${date.format()} renders dates in templates. It also set the default date format when binding a date parameter.

Default: yyyy-MM-dd

You can also set a different date format for specific languages that you have configured with application.langs, for example:

Database configuration


Database engine configuration. To quickly set up a development database use a transient in memory database (H2 in memory):


For a simple file written database (H2 file stored):


For a local MySQL5 database:


To reuse an existing Datasource from your application server:


If you specify a Datasource, the database plugin detects the pattern db=java: and will de-activate the default JDBC system.

Default: none.

See also: Support for multiple databases.

h3(#db.destroyMethod). db.destroyMethod

A generic ‘destroy’ method name. When using an existing Datasource, this is sometimes needed to destroy it when the application is stopped. For example:


Default: none.

h3(#db.driver). db.driver

Database driver class name, for use with db.url. For example:



  • org.h2.Driver when db is set to mem or fs, or if db.url starts with jdbc:h2:mem:
  • com.mysql.jdbc.Driver if db is a mysql:… configuration.

h3(#db.isolation). db.isolation

Database transaction isolation level. For example:


Valid values are NONE, READ_UNCOMMITTED, READ_COMMITTED, REPEATABLE_READ, SERIALIZABLE, or an integer value to be passed to java.sql.Connection.setTransactionIsolation(). Note that not all databases support all transaction isolation levels.

Default: database dependent, usually READ_COMMITTED

h3(#db.pass). db.pass

Database connection password, used with db.url.

Default: no value, or an empty string when db is set to mem or fs.

h3(#db.pool.maxIdleTimeExcessConnections). db.pool.maxIdleTimeExcessConnections

The number of seconds before idle connections beyond db.pool.minSize are ‘culled’. See the c3p0 documentation.

Default: 0 – ‘no enforcement’.

h3(#db.pool.maxSize). db.pool.maxSize

Connection pool maximum size (number of connections). See the c3p0 documentation. For example:


Default: 30

h3(#db.pool.minSize). db.pool.minSize

Connection pool minimum size (number of connections). See the c3p0 documentation. For example:


Default: 1

h3(#db.pool.timeout). db.pool.timeout

Connection pool time-out in milliseconds. See the c3p0 documentation. For example:


Default: 5000

h3(#db.url). db.url

A full JDBC configuration, in combination with db.user, db.pass and db.driver. For example:


Default: none.

h3(#db.user). db.user

Database connection user name, used with db.url.

Default: none, or sa when db is set to mem or fs.

Database evolutions

h3(#evolutions.enabled). evolutions.enabled

Used to disable database evolutions.


Default: true

Test runner


Specifies the web browser compatibility mode for the HtmlUnit headless web browser used when running play auto-test.



  • FIREFOX_3_6



You can specify additional Hibernate properties. For example, to enable SQL comments:


See also: Using JPA with multiple databases.

h3(#hibernate.connection.datasource). hibernate.connection.datasource

Hibernate datasource configuration.

Server configuration

h3(#http.address). http.address

HTTP listener address, to restrict addresses the server listens on. For example:


Default: the server listens for HTTP on the wildcard address.

h3(#http.cacheControl). http.cacheControl

HTTP Response headers control for static files: sets the default max-age in seconds, telling the user’s browser how long it should cache the page. This is only read in prod mode, in dev mode the cache is disabled. For example, to send no-cache:


Default: 3600 – set cache expiry to one hour.

h3(#http.exposePlayServer). http.exposePlayServer

Disable the HTTP response header that identifies the HTTP server as Play. For example:


Default: true

h3(#http.path). http.path

The URL path where the application runs on the server: use this if you do not host your Play application at the root of the domain you’re serving it from. This parameter has no effect when deployed as a WAR, because the path will be handled by the application server. For example:


Default: /

h3(#http.port). http.port

The port that the HTTP server listens on.

Default: 9000

h3(#http.proxyHost). http.proxyHost

Proxy server for web services requests. For example:


Default: http.proxyHost system property.

h3(#http.proxyPassword). http.proxyPassword

Proxy password for web services requests.

Default: http.proxyPassword system property.

h3(#http.proxyPort). http.proxyPort

Proxy port for web services requests. For example:


Default: http.proxyPort system property.

h3(#http.proxyUser). http.proxyUser

Proxy user for web services requests.

Default: http.proxyUser system property.

h3(#http.nonProxyHosts). http.nonProxyHosts

Indicates the hosts which should be connected to directly and not through the proxy server.
The value can be a list of hosts, each seperated by a |, and in addition a wildcard character * can be used for matching.

For example:


Default: http.nonProxyHosts system property.

h3(#http.useETag). http.useETag

If enabled, Play will generate entity tags automatically and send a 304 when needed. For example, to deactivate use of entity tags:


Default: true

h3(#http.userAgent). http.userAgent

Custom USER_AGENT header value for web services requests. For example:

http.userAgent=myApp 1.0

Default: none.

h3(#https.port). https.port

Enables an HTTPS connector, listening on the specified port. For example:


Default: none – no HTTPS configuration.

Java source

h3(#java.source). java.source

Java source level, which overrides the java.version system property. For example:


Values: 1.5, 1.6, 1.7 (experimental).

Default: 1.5


h3(#jpa.dialect). jpa.dialect

Specify the custom JPA dialect to use here. For example:


Default: Play will guess the dialect based on the db.driver configuration.

h3(#jpa.ddl). jpa.ddl

Specify the DDL generation pattern to use. For example, to enable automatic database structure updates. For example:


Default: update (dev mode) or none (prod mode).

h3(#jpa.debugSQL). jpa.debugSQL

Debug SQL statements (logged using DEBUG level). For example:


Default: false

h3(#jpa.entities). jpa.entities

Comma-separated list of names of additional JPA entity classes to load. This is useful when you have additional entities that are not in the models package, such as model classes in a separate JAR. For example:

org.example.model.Person, org.example.model.Organisation

Default: none.

h3(#jpa.mapping-file). jpa.mapping-file

JPA mapping file.

Default: none.


h3(#jpda.port). jpda.port

Defines which port is used by JPDA when application is in debug mode. For example:

Default: 8000


h3(#keystore.algorithm). keystore.algorithm

A JDK Security API standard algorithm name, for use with the keystore.file configuration.


Values – ‘standard names’ from the JDK Security API:

  • jceks (‘SunJCE’ provider)
  • jks (‘SUN" provider)
  • pkcs12

Default: JKS

h3(#keystore.file). keystore.file

Specifies a keystore certificate, for HTTPS support. The file should be named certificate.jks. For example:


h3(#keystore.password). keystore.password

Keystore configuration, for use with the keystore.file configuration.


Default: secret



Enable Memcached; if you don’t configure Memcached, Play will use a standalone cache that stores data in the JVM heap.


Default: disabled

See also: using a cache.


Specify memcached host. For example:


You can specify multiple hosts to build a distributed cache. For example:

Custom MIME types

You can declare additional MIME types. For example:


Web services


Class name of the Web services implementation, or one of the built-in implementations. For example:



  • urlfetch – the JDK’s internal implementation
  • async – the engine is Async Http Client
  • class name of a play.libs.WS.WSImpl implementation

Default: async – the engine is Async Http Client.


h3(#mail.debug). mail.debug

Enables SMTP transaction logging; under the hood, Play uses JavaMail to perform the actual SMTP transactions.


Default: false

h3(#mail.smtp). mail.smtp

Simple mail configuration key.

Default: mock – use a mock Mailer

See also: SMTP configuration.

h3(#mail.smtp.authenticator). mail.smtp.authenticator

Class name for a custom SMTP authenticator (javax.mail.Authenticator) implementation.

Default: none.


There are two ways to send the e-mail over an encrypted channel, which you can choose with this configuration property. Values:

  • clear – no encryption
  • ssl – SMTP-over-SSL (SMTPS) connector; an SSL socket listening on port 465
  • starttls – a clear connection on port 25 that will switch to SSL/TLS, if your server supports the starttls command (see: RFC 2487).

Default: clear


Outgoing mail server. For example:

To use a GMail SMTP server:

Default: localhost

h3(#mail.smtp.localhost). mail.smtp.localhost

Local host name override for SMTP commands.

Default: none – use the Java Mail default.

h3(#mail.smtp.pass). mail.smtp.pass

SMTP server password, used with, e.g. a GMail password.

Default: none.

h3(#mail.smtp.port). mail.smtp.port

Port for SMTP server connections, used to override the defaults. For example:



h3(#mail.smtp.protocol). mail.smtp.protocol

Sets whether to use SSL. Values:

  • smtp
  • smtps

Default: smtp

h3(#mail.smtp.socketFactory.class). mail.smtp.socketFactory.class

When using SSL connections with JavaMail, the default SSL behaviour is to drop the connection if the remote server certificate is not signed by a root certificate. This is the case in particular when using a self-signed certificate. Play’s default behaviour is to skip that check. You can control this using this property.

h3(#mail.smtp.user). mail.smtp.user

SMTP server user name, used with, e.g. a GMail user name.

Default: none.

Play run-time

h3(#play.bytecodeCache). play.bytecodeCache

Used to disable the bytecode cache in dev mode; has no effect in prod mode.


Default: true

h3(#play.editor). play.editor

Open file from error pages. If your text editor supports opening files by URL, Play will dynamically link error pages to files. For Textmate, for example:



Size of the Jobs pool. For example:

Default: 10

h3(#play.netty.clientAuth). play.netty.clientAuth

Configures client authentication. For example:



  • want – the server will request client authentication
  • need – the server will require client authentication
  • none – no client authentication

Default: none

h3(#play.netty.maxContentLength). play.netty.maxContentLength

HTTP server maximum content length for response streaming, in bytes.

Default: none – no maximum.

h3(#play.ssl.enabledCiphers). play.ssl.enabledCiphers

This setting allows to specify certain SSL ciphers to be used. This might be needed in case you have to be PCI compliant, as some ciphers in the default settings are vulnerable to the so-called BEAST attack.


Default: none – the default ciphers are chosen.

h3(#play.pool). play.pool

Execution pool size. Try to keep this as low as possible. Setting this to 1 thread will serialise all requests (very useful for debugging purpose). For example:


Default: 1 (in dev mode), number of processors + 1 (in prod mode).

h3(#play.tmp). play.tmp

Folder used to store temporary files. For example:



  • an absolute path
  • a relative path, relative to the application directory
  • none so that no temporary directory will be used

Default: tmp


See also: https.port.

h3(#ssl.KeyManagerFactory.algorithm). ssl.KeyManagerFactory.algorithm

The standard name of a Java Secure Socket Extension (JSSE) trust management algorithm, for use with the keystore.file configuration.


Default: SunX509


h3(#trustmanager.algorithm). trustmanager.algorithm

A JDK Security API standard algorithm name, for use with X509 certificates and keystore configurations.


Values – ‘standard names’ from the JDK Security API:

  • jceks (‘SunJCE’ provider)
  • jks (‘SUN" provider)
  • pkcs12

Default: JKS

File upload

h3(#upload.threshold). upload.threshold

The threshold in bytes at which upload files will be written to disk, for For example:


Default: 10240

Proxy forwarding


Overrides the X-Forwarded-Host HTTP header value – the original host requested by the client, for use with proxy servers.

Default: X-Forwarded-Host HTTP header value.


Sets the proxy request to SSL, overriding the X-Forwarded-Proto and X-Forwarded-SSL HTTP header values – the protocol originally requested by the client. For example:



A comma-separated list of IP addresses that are allowed X-Forwarded-For HTTP request header values, used to restrict local addresses when an X-Forwarded-For request header is set by a proxy server.


Jump to Line
Something went wrong with that request. Please try again.