Configure your Play application by setting values for configuration keys in conf/application.conf
file. See also:
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/
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.
Forces all reverse routes and controller action redirection to be secure (https). This is useful for SSL-enabled apps to prevent insecure (http) url generation when redirecting to another action from inside your controllers, or when using the @{..}
template syntax. For example:
application.forceSecureReverseRoutes=true
Default: false
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
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.
Specifies log level for your application. For example:
application.log=DEBUG
Default: INFO
See also: Logging configuration.
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
Configures the value of play.Logger.recordCaller
to record and display the caller method. For example:
application.log.recordCaller=true
Default: false
Application mode (case insensitive). For example:
application.mode=prod
Values:
DEV
- enable instant reloading and other development helpPROD
- pre-compiles and caches Java sources and templates.Default: DEV
The application’s name, usually set by the play new
command.
Default: no value.
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.
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.
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.
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.
Enables Cookie-based sessions for HTTPS connections. For example:
application.session.secure=true
Default: false
Avoid sending the session cookie if there were no changes to the session. For example:
application.session.sendOnlyIfChanged=true
Default: false
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.
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
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
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
Password for a password-protected X509 certificate key file, for use with the certificate.key.file configuration. For example:
certificate.password=secret
Default: secret
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 * * ?
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
You can configure Play to use a single or multiple (separate) 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 databasejpa
will be replaced by jpa.[DB_name]
where [DB_name]
is the name of the databasehibernate
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");
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@
And for application server where Datasource doesn’t have java:
prefix (Glassfish and its derivative), you could use jndi:
instead. The jndi:
prefix will be omitted:
db=jndi:jdbc/myDataSource
If you specify a Datasource
, the database plugin detects the pattern db=java:
and db=jndi:
and will de-activate the default JDBC system.
Default: none.
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.
Database driver class name, for use with db.url. For example:
db.driver=org.postgresql.Driver
Default:
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.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
Database connection password, used with db.url.
Default: no value, or an empty string when db is set to mem
or fs
.
Determines how many connections at a time c3p0 will try to acquire when the pool is exhausted.
Default: 3
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
Milliseconds, time c3p0 will wait between acquire attempts.
Default: 1000
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
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
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
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
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
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
Seconds a Connection can remain pooled but unused before being discarded. Zero means idle connections never expire.
Default: 0
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
The number of seconds before idle connections beyond db.pool.minSize are ‘culled’. See the c3p0 documentation.
Default: 0
- ‘no enforcement’.
Connection pool maximum size (number of connections). See the c3p0 documentation. For example:
db.pool.maxSize=60
Default: 30
Connection pool minimum size (number of connections). See the c3p0 documentation. For example:
db.pool.minSize=10
Default: 1
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
Connection pool time-out in milliseconds. See the c3p0 documentation. For example:
db.pool.timeout=10000
Default: 5000
Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.
Default: 0
The size of c3p0’s global PreparedStatement cache. If both maxStatements and maxStatementsPerConnection are zero, statement caching will not be enabled.
Default: 0
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
A full JDBC configuration, in combination with db.user, db.pass and db.driver. For example:
db.url=jdbc:postgresql:database_name
Default: none.
Database connection user name, used with db.url.
Default: none, or sa
when db is set to mem
or fs
.
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
Seconds before c3p0’s thread pool will try to interrupt an apparently hung task. Rarely useful.
Default: 0
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
Used to disable database evolutions.
evolutions.enabled=false
Default: true
Used to disable database evolutions from all modules
modules.evolutions.enabled=false
Default: true
Used to disable database evolutions from a given module
[module name].evolutions.enabled=false
Default: true
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
Specifies the web browser compatibility mode for the HtmlUnit headless web browser used when running play auto-test
.
headlessBrowser=FIREFOX_38
Values:
CHROME
FIREFOX_31
INTERNET_EXPLORER_8
INTERNET_EXPLORER_11
EDGE
Default: FIREFOX_38
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
You can specify additional Hibernate properties. For example, to enable SQL comments:
hibernate.use_sql_comments=true
Hibernate datasource configuration.
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 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.
Disable the HTTP response header that identifies the HTTP server as Play. For example:
http.exposePlayServer=false
Default: true
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: /
The port that the HTTP server listens on.
Default: 9000
Proxy server for web services requests. For example:
http.proxyHost=localhost
Default: http.proxyHost
system property.
Proxy password for web services requests.
Default: http.proxyPassword
system property.
Proxy port for web services requests. For example:
http.proxyPort=3128
Default: http.proxyPort
system property.
Proxy user for web services requests.
Default: http.proxyUser
system property.
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.
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
Custom USER_AGENT
header value for web services requests. For example:
http.userAgent=myApp 1.0
Default: none.
Enables an HTTPS connector, listening on the specified port. For example:
https.port=9443
Default: none – no HTTPS configuration.
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
You can configure Play to use a single or multiple (separate) 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");
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.
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).
Debug SQL statements (logged using DEBUG level). For example:
jpa.debugSQL=true
Default: false
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.
Default: none.
Defines which port is used by JPDA when application is in debug mode. For example:
Default: 8000
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:
jceks
(‘SunJCE’ provider)jks
(‘SUN" provider)pkcs12
Default: JKS
Specifies a keystore certificate, for HTTPS support. The file should be named certificate.jks
. For example:
keystore.file=conf/certificate.jks
Keystore configuration, for use with the keystore.file configuration.
keystore.password=secret
Default: secret
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.
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
You can declare additional MIME types. For example:
mimetype.xpi=application/x-xpinstall
Class name of the Web services implementation, or one of the built-in implementations. For example:
webservice=urlfetch
Values:
urlfetch
- the JDK’s internal implementationasync
- the engine is Async Http Clientplay.libs.WS.WSImpl
implementationDefault: async
- the engine is Async Http Client.
Enables SMTP transaction logging; under the hood, Play uses JavaMail to perform the actual SMTP transactions.
mail.debug=true
Default: false
Simple mail configuration key.
Default: mock
- use a mock Mailer
See also: SMTP configuration.
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 encryptionssl
- SMTP-over-SSL (SMTPS) connector; an SSL socket listening on port 465starttls
- 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:
mail.smtp.host=127.0.0.1
To use a GMail SMTP server:
mail.smtp.host=smtp.gmail.com
Default: localhost
Local host name override for SMTP commands.
Default: none – use the Java Mail default.
SMTP server password, used with mail.smtp.host, e.g. a GMail password.
Default: none.
Port for SMTP server connections, used to override the defaults. For example:
mail.smtp.port=2500
Default:
25
when mail.smtp.channel is set to clear
or starttls
465
when mail.smtp.channel is set to ssl
Sets whether to use SSL. Values:
smtp
smtps
Default: smtp
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.
SMTP server user name, used with mail.smtp.host, e.g. a GMail user name.
Default: none.
Used to disable the bytecode cache in dev
mode; has no effect in prod
mode.
play.bytecodeCache=false
Default: true
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
Size of the Jobs pool. For example:
play.jobs.pool=20
Default: 10
Configures javax.net.ssl.SSLEngine
client authentication. For example:
play.netty.clientAuth=need
Values:
want
- the server will request client authenticationneed
- the server will require client authenticationnone
- no client authenticationDefault: none
HTTP server maximum content length for response streaming, in bytes.
Default: none – no maximum.
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.
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.
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).
The value is a list of files separated by a property like "path.separator
":configuration#play.templates.compile.path.separator .
play.templates.compile=/absolue/path/file.ext;conf/relative/path/file.ext;{module:reporting}module/relative/path/file.ext
The path notation of files can use:
Default: no default the parameter is optional
Override the path separator for separating list elements of play.templates.compile
":configuration#play.templates.compile .
This parameter would be usefull when using the path notation for module relative file path on unix systems,
where the default value would be :
. That would separate module prefix notations like {module:modname}
on unix.
play.templates.compile.path.separator=;
Default: the system property path.separator
Folder used to store temporary files. For example:
play.tmp=/tmp/play
Values:
none
so that no temporary directory will be usedDefault: tmp
See also: https.port.
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
Allows for custom SSL certificates to be used with connection initiated through WebServices
The custom keystore that should be added to Play! WebServices connections
The password neede to access the keys inside the keystore. This is required.
If set to true, the CA chain is validated upon connection.
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:
jceks
(‘SunJCE’ provider)jks
(‘SUN" provider)pkcs12
Default: JKS
play.netty.clientAuth
Values
want
Controls whether accepted server-mode SSLSockets will be initially configured to request client authentication. need
Controls whether accepted server-mode SSLSockets will be initially configured to require client authentication.none
None of the aboveDefault: none
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
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:
XForwardedProto=https
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
Set to true to restore the request domain and port to original domain and port.
For example:
XForwardedOverwriteDomainAndPort=true
Default: false
Used to disable play enhancing of play class (can be used to switch off default constructors/getter/setter generation). For example:
play.propertiesEnhancer.enabled=false
Default: true
Used to partially disable PropertyEnhancer. Namely, it switches off generating getters/setters and replacing
all direct field accesses with getters/setters (which is the slowest part of “play precompile”).
But it leaves generating default constructors.
For example:
play.propertiesEnhancer.generateAccessors=false
Default: true