Documentation

You are viewing the documentation for Play 1. The documentation for Play 2 is here.

Configuration parameters

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

Application configuration

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:

application.baseUrl=http://localhost:9000/

For prod mode:

%production.application.baseUrl=http://www.yourdomain.com/

application.defaultCookieDomain

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

application.defaultCookieDomain=.example.com

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

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:

application.lang.cookie=MYAPP_LANG

Default: PLAY_LANG

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:

application.langs=fr,en,ja

Default: no additional languages.

application.log

Specifies log level for your application. For example:

application.log=DEBUG

Default: INFO

See also: Logging configuration.

application.log.path

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

application.log.path=/log4j.properties

Default: /log4j.xml falling back to /log4j.properties

application.log.recordCaller

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

application.log.recordCaller=true

Default: false

application.mode

Application mode (case insensitive). For example:

application.mode=prod

Values:

Default: DEV

application.name

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

Default: no value.

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:

application.secret=mNuAvlsFVjeuynN4IWZxZzFOHYVagafzjruHmWTL26VISKr46rUtyGcJuX7aYx4q

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

Default: no value.

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:

application.session.cookie=PLAY

Default: sessions are written to the transient PLAY_SESSION cookie.

application.session.httpOnly

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

application.session.httpOnly=true

Default: false

For more information see the OWASP page on HttpOnly.

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:

application.session.maxAge=1h

Remember the session for one week:

application.session.maxAge=7d

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

application.session.secure

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

application.session.secure=true

Default: false

application.session.sendOnlyIfChanged

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

application.session.sendOnlyIfChanged=true

Default: false

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:

application.web_encoding=ISO-8859-1

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.

Attachments

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:

attachments.path=data/attachments

Default: attachments

X509 certificates

certificate.key.file

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

certificate.key.file=/certificates/host.key

Default: conf/host.key

certificate.file

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

certificate.file=/certificates/host.cert

Default: conf/host.cert

certificate.password

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

certificate.password=secret

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 @play.jobs.On or @Every annotation. For example, @On(“cron.noon”) refers to:

cron.noon=0 0 12 * * ?

Date formats

date.format

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

date.format=dd-MM-yyyy

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:

date.format.fr=dd-MM-yyyy

Databases configuration (Single-DB or multi-DB)

You can configure Play to use a single or multiple (separate) databases.

Support for multiple databases

You can specify a specific database or the default configuration.
All these parameters can be used to configure a specific database by replacing db by db.[DB_name] where [DB_name] is the name of the database.

The default database is configured by configuration parameters in conf/application.conf whose keys start with ‘db.’ (e.g: db.url).
To configure an additional database, add a dot and a suffix (name of the database) to the ‘db’ part of the key, like this:

Example:

db will be replaced by db.[DB_name] where [DB_name] is the name of the database
jpa will be replaced by jpa.[DB_name] where [DB_name] is the name of the database
hibernate will be replaced by hibernate.[DB_name] where [DB_name] is the name of the database

This database configuration is now called ‘DB_name’ in Play. For example, configure DB/JPA/hibernate for this ‘DB_name’ configuration like this:

Example, with 3 tables “default”, “student” and "teacher"

db.default.[param]
db.student.[param]
db.teacher.[param]

You can then access this database from your application’s Java by using this name like this:

EntityManager em = JPA.em("student");

db

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

db=mem

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

db=fs

For a local MySQL5 database:

db=mysql:user:pwd@database_name

To reuse an existing Datasource from your application server:

db=java:/comp/env/jdbc/myDatasource@

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

Default: none.

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:

db.destroyMethod=close

Default: none.

db.driver

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

db.driver=org.postgresql.Driver

Default:

db.isolation

Database transaction isolation level. For example:

db.isolation=SERIALIZABLE

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

db.pass

Database connection password, used with db.url.

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

db.pool.acquireIncrement

Determines how many connections at a time c3p0 will try to acquire when the pool is exhausted.

Default: 3

db.pool.acquireRetryAttempts

Defines how many times c3p0 will try to acquire a new Connection from the database before giving up. If this value is less than or equal to zero, c3p0 will keep trying to fetch a Connection indefinitely.

Default: 10

db.pool.acquireRetryDelay

Milliseconds, time c3p0 will wait between acquire attempts.

Default: 1000

db.pool.breakAfterAcquireFailure

If true, a pooled DataSource will declare itself broken and be permanently closed if a Connection cannot be obtained from the database after making acquireRetryAttempts to acquire one. If false, failure to obtain a Connection will cause all Threads waiting for the pool to acquire a Connection to throw an Exception, but the DataSource will remain valid, and will attempt to acquire again following a call to getConnection().

Default: false

db.pool.unreturnedConnectionTimeout

Seconds. If set, if an application checks out but then fails to check-in [i.e. close()] a Connection within the specified period of time, the pool will unceremoniously destroy() the Connection. This permits applications with occasional Connection leaks to survive, rather than eventually exhausting the Connection pool. And that’s a shame. Zero means no timeout, applications are expected to close() their own Connections. Obviously, if a non-zero value is set, it should be to a value longer than any Connection should reasonably be checked-out. Otherwise, the pool will occasionally kill Connections in active use, which is bad.

Use this temporarily in combination with debugUnreturnedConnectionStackTraces to figure out where Connections are being checked-out that don’t make it back into the pool!

Default: 0

db.pool.debugUnreturnedConnectionStackTraces

f true, and if unreturnedConnectionTimeout is set to a positive value, then the pool will capture the stack trace (via an Exception) of all Connection checkouts, and the stack traces will be printed when unreturned checked-out Connections timeout. This is intended to debug applications with Connection leaks, that is applications that occasionally fail to return Connections, leading to pool growth, and eventually exhaustion (when the pool hits maxPoolSize with all Connections checked-out and lost). This parameter should only be set while debugging, as capturing the stack trace will slow down every Connection check-out.

Default: false

db.pool.testConnectionOnCheckout

If true, an operation will be performed at every connection checkout to verify that the connection is valid. Be sure to set an efficient preferredTestQuery or automaticTestTable if you set this to true. Performing the (expensive) default Connection test on every client checkout will harm client performance. Testing Connections in checkout is the simplest and most reliable form of Connection testing, but for better performance, consider verifying connections periodically using idleConnectionTestPeriod.

Default: false

db.pool.testConnectionOnCheckin

If true, an operation will be performed asynchronously at every connection checkin to verify that the connection is valid. Use in combination with idleConnectionTestPeriod for quite reliable, always asynchronous Connection testing. Also, setting an automaticTestTable or preferredTestQuery will usually speed up all connection tests.

Default: true

db.pool.maxConnectionAge

Seconds, effectively a time to live. A Connection older than maxConnectionAge will be destroyed and purged from the pool. This differs from maxIdleTime in that it refers to absolute age. Even a Connection which has not been much idle will be purged from the pool if it exceeds maxConnectionAge. Zero means no maximum absolute age is enforced.

Default: 0

db.pool.maxIdleTime

Seconds a Connection can remain pooled but unused before being discarded. Zero means idle connections never expire.

Default: 0

db.pool.idleConnectionTestPeriod

If this is a number greater than 0, c3p0 will test all idle, pooled but unchecked-out connections, every this number of seconds.

Default: 10

db.pool.maxIdleTimeExcessConnections

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

Default: 0 - ‘no enforcement’.

db.pool.maxSize

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

db.pool.maxSize=60

Default: 30

db.pool.minSize

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

db.pool.minSize=10

Default: 1

db.pool.initialSize

Number of Connections a pool will try to acquire upon startup. Should be between minPoolSize and maxPoolSize. See the c3p0 documentation. For example:

db.pool.initialSize=5

Default: 1

db.pool.timeout

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

db.pool.timeout=10000

Default: 5000

db.pool.loginTimeout

Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.

Default: 0

db.pool.maxStatements

The size of c3p0’s global PreparedStatement cache. If both maxStatements and maxStatementsPerConnection are zero, statement caching will not be enabled.

Default: 0

db.pool.maxStatementsPerConnection

The number of PreparedStatements c3p0 will cache for a single pooled Connection. If both maxStatements and maxStatementsPerConnection are zero, statement caching will not be enabled.

Default: 0

db.url

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

db.url=jdbc:postgresql:database_name

Default: none.

db.user

Database connection user name, used with db.url.

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

db.testquery

Override query to use when keepalive connection polling is being performed. The default value will cause keepalive to fetch metadata. This means it does a getTables() which can be a heavy operation on a busy databse.

Default: null
Default on MySQL: /* ping */ SELECT 1

db.pool.maxAdministrativeTaskTime

Seconds before c3p0’s thread pool will try to interrupt an apparently hung task. Rarely useful.

Default: 0

db.pool.numHelperThreads

c3p0 is very asynchronous. Slow JDBC operations are generally performed by helper threads that don’t hold contended locks. Spreading these operations over multiple threads can significantly improve performance by allowing multiple operations to be performed simultaneously.

Default: 3

Database evolutions

evolutions.enabled

Used to disable database evolutions.

evolutions.enabled=false

Default: true

modules.evolutions.enabled

Used to disable database evolutions from all modules

modules.evolutions.enabled=false

Default: true

[module name].evolutions.enabled

Used to disable database evolutions from a given module

[module name].evolutions.enabled=false

Default: true

evolution.PLAY_EVOLUTIONS.textType

If you are having problems with the default datatype text (clob for Oracle), you can specify your own datatype 

evolution.PLAY_EVOLUTIONS.textType=clob

Default: clob

Test runner

headlessBrowser

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

headlessBrowser=FIREFOX_31

Values:

Default: FIREFOX_31

webclient.timeout

Specifies the timeout of the WebConnection. Set to zero for an infinite wait.

Note: The timeout is used twice. The first is for making the socket connection, the second is for data retrieval. If the time is critical you must allow for twice the time specified here.

webclient.timeout=60

This value can be set directly in the command play auto-test by adding --timeout=60

Hibernate

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

hibernate.use_sql_comments=true

hibernate.connection.datasource

Hibernate datasource configuration.

Server configuration

http.address

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

http.address=127.0.0.1

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

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:

http.cacheControl=0

Default: 3600 - set cache expiry to one hour.

http.exposePlayServer

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

http.exposePlayServer=false

Default: true

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:

http.path=/myapp/

Default: /

http.port

The port that the HTTP server listens on.

Default: 9000

http.proxyHost

Proxy server for web services requests. For example:

http.proxyHost=localhost

Default: http.proxyHost system property.

http.proxyPassword

Proxy password for web services requests.

Default: http.proxyPassword system property.

http.proxyPort

Proxy port for web services requests. For example:

http.proxyPort=3128

Default: http.proxyPort system property.

http.proxyUser

Proxy user for web services requests.

Default: http.proxyUser system property.

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:

http.nonProxyHosts=localhost|*.example.com

Default: http.nonProxyHosts system property.

http.useETag

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

http.useETag=false

Default: true

http.userAgent

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

http.userAgent=myApp 1.0

Default: none.

https.port

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

https.port=9443

Default: none – no HTTPS configuration.

Java source

java.source

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

java.source=1.7

Values: 1.5 (No longer supported since 1.3.0), 1.6, 1.7, 1.8 (experimental).

Default: 1.6

JPA

You can configure Play to use a single or multiple (separate) databases.

Support for multiple databases

You can specify a specific database or the default configuration.
All these parameters can be used to configure a specific database by replacing db by db.[DB_name] where [DB_name] is the name of the database.

The default database is configured by configuration parameters in conf/application.conf whose keys start with ‘jpa.’ (e.g: db.url).
To configure an additional database, add a dot and a suffix (name of the database) to the ‘jpa’ part of the key, like this:

Example:

jpa will be replaced by jpa.[DB_name] where [DB_name] is the name of the database

This database configuration is now called ‘DB_name’ in Play. For example, configure JPA for this ‘DB_name’ configuration like this:

Example, with 3 tables “default”, “student” and "teacher"

jpa.default.[param]
jpa.student.[param]
jpa.teacher.[param]

You can then access this database from your application’s Java by using this name like this:

EntityManager em = JPA.em("student");

jpa.dialect

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

jpa.dialect=org.hibernate.dialect.PostgreSQLDialect

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

jpa.ddl

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

jpa.ddl=create-drop

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

jpa.debugSQL

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

jpa.debugSQL=true

Default: false

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.

jpa.mapping-file

JPA mapping file.

Default: none.

JVM

jpda.port

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

Default: 8000

keystore

keystore.algorithm

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

keystore.algorithm=pkcs12

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

Default: JKS

keystore.file

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

keystore.file=conf/certificate.jks

keystore.password

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

keystore.password=secret

Default: secret

Memcached

memcached

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

memcached=enabled

Default: disabled

See also: using a cache.

memcached.host

Specify memcached host. For example:

memcached.host=127.0.0.1:11211

Default: 127.0.0.1:11211

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

memcached.1.host=127.0.0.1:11211
memcached.2.host=127.0.0.1:11212

Custom MIME types

You can declare additional MIME types. For example:

mimetype.xpi=application/x-xpinstall

Web services

webservice

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

webservice=urlfetch

Values:

Default: async - the engine is Async Http Client.

Mail

mail.debug

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

mail.debug=true

Default: false

mail.smtp

Simple mail configuration key.

Default: mock - use a mock Mailer

See also: SMTP configuration.

mail.smtp.authenticator

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

Default: none.

mail.smtp.channel

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

Default: clear

mail.smtp.host

Outgoing mail server. For example:

mail.smtp.host=127.0.0.1

To use a GMail SMTP server:

mail.smtp.host=smtp.gmail.com

Default: localhost

mail.smtp.localhost

Local host name override for SMTP commands.

Default: none – use the Java Mail default.

mail.smtp.pass

SMTP server password, used with mail.smtp.host, e.g. a GMail password.

Default: none.

mail.smtp.port

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

mail.smtp.port=2500

Default:

mail.smtp.protocol

Sets whether to use SSL. Values:

Default: smtp

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.

mail.smtp.user

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

Default: none.

Play run-time

play.bytecodeCache

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

play.bytecodeCache=false

Default: true

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:

play.editor=txmt://open?url=file://%s&line=%s

play.jobs.pool

Size of the Jobs pool. For example:

play.jobs.pool=20

Default: 10

play.netty.clientAuth

Configures javax.net.ssl.SSLEngine client authentication. For example:

play.netty.clientAuth=need

Values:

Default: none

play.netty.maxContentLength

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

Default: none – no maximum.

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.

play.ssl.enabledCiphers=SSL_RSA_WITH_RC4_128_MD5,SSL_RSA_WITH_RC4_128_SHA

Default: none – the default ciphers are chosen.

play.ssl.enabledProtocols

This setting allows to specify certain SSL protocols to be used.

play.ssl.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2

Default: none – the default protocols are chosen.

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:

play.pool=10

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

play.tmp

Folder used to store temporary files. For example:

play.tmp=/tmp/play

Values:

Default: tmp

SSL

See also: https.port.

ssl.KeyManagerFactory.algorithm

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

ssl.KeyManagerFactory.algorithm=SunX509

Default: SunX509

Custom key stores

Allows for custom SSL certificates to be used with connection initiated through WebServices

ssl.Keystore

The custom keystore that should be added to Play! WebServices connections

ssl.keyStorePassword

The password neede to access the keys inside the keystore. This is required.

ssl.cavalidation

If set to true, the CA chain is validated upon connection.

trustmanager

trustmanager.algorithm

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

trustmanager.algorithm=pkcs12

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

Default: JKS

play.netty.clientAuth

Values

Default: none

File upload

upload.threshold

The threshold in bytes at which upload files will be written to disk, for org.apache.commons.io.output.DeferredFileOutputStream. For example:

upload.threshold=20480

Default: 10240

Proxy forwarding

XForwardedHost

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.

XForwardedProto

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:

XForwardedProto=https

XForwardedSupport

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. Alternatively you can use ‘ALL’ if you do not want to restrict local addresses. Note: only use ‘ALL’ if you are very sure that if it safe to do so (e.g. you have a proper firewall in place that blocks public requests). A valid use-case would be when using Play! behind a Amazon ELB loadbalancer, which internal IP’s tend to change over time.

Default: 127.0.0.1

XForwardedOverwriteDomainAndPort

Set to true to restore the request domain and port to original domain and port.

For example:

XForwardedOverwriteDomainAndPort=true

Enhancers

play.propertiesEnhancer.enabled

Used to disable play enhancing of play class (can be used to switch off getter/setter generation). For example:

play.propertiesEnhancer.enabled=false

Default: true