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

Database configuration

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.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.timeout

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

db.pool.timeout=10000

Default: 5000

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

Database evolutions

evolutions.enabled

Used to disable database evolutions.

evolutions.enabled=false

Default: true

Test runner

headlessBrowser

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

headlessBrowser=INTERNET_EXPLORER_7

Values:

Default: INTERNET_EXPLORER_8

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.6

Values: 1.5, 1.6, 1.7 (experimental).

Default: 1.5

JPA

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