Fork me on GitHub

As described here, Isis itself bootstraps from the configuration file. It will also read configuration from the (optional) component/implementation-specific configuration files (such as or and also (otional) component-specific configuration files (such as or

By convention we put JDBC URL properties in, but they could reside in any of, or (even)

By default these are read from the WEB-INF directory. Having this configuration "baked into" the application is okay in a development environment, but when the app needs to be deployed to a test or production environment, this configuration should be read from an external location.

There are in fact three frameworks involved here, all of which need to be pointed to this external location:

Each of these frameworks has its own way of externalizing its configuration.

Externalizing Isis' Configuration

Note that running the app from org.apache.isis.WebServer currently does not externalized Isis configuration.

To tell Isis to load configuration from an external directory, specify the isis.config.dir context parameter.

If the external configuration directory is fixed for all environments (systest, UAT, prod etc), then you can specify within the web.xml itself:

    <param-value>location of external config directory</param-value>

If however the configuration directory varies by environment, then the context parameter will be specified to each installation of your servlet container. Most (if not all) servlet containers will provide a means to define context parameters through proprietary config files.

For example, if using Tomcat 7.0, you would typically copy the empty $TOMCAT_HOME/webapps/conf/context.xml to a file specific to the webapp, for example $TOMCAT_HOME/webapps/conf/todo.xml. The context parameter would then be specified by adding the following:

<Parameter name="isis.config.dir"

For more detail, see the Tomcat documentation on defining a context and on context parameters.

Externalizing Shiro's Configuration

If using Isis' Shiro integration for authentication and/or authorization, note that it reads from the shiro.ini configuration file. By default this also resides in WEB-INF.

Similar to Isis, Shiro lets this configuration directory be altered, by specifying the shiroConfigLocations context parameter.

You can therefore override the default location using the same technique as described above for Isis' isis.config.dir context parameter. For example:

<Parameter name="shiroConfigLocations" 
           override="true" />

Note that Shiro is more flexible than Isis; it will read its configuration from any URL, not just a directory on the local filesystem.

Externalizing Log4j's Configuration

By default Isis configures log4j to read the file in the WEB-INF directory. This can be overridden by setting the system property to the URL of the log4j properties file.

For example, if deploying to Tomcat7, this amounts to adding the following to the CATALINA_OPTS flags:

export CATALINA_OPTS="-Dlog4j.configuration=/usr/local/tomcat/myapp/conf/"

Further details an be found in the log4j documentation.

CATALINA_OPTS was called TOMCAT_OPTS in earlier versions of Tomcat.

See also

See JVM args for other JVM args and system properties that you might want to consider setting.