Skip to content
Permalink
Browse files
updating old .md files.
  • Loading branch information
danhaywood committed Jun 26, 2015
1 parent 18f75b9 commit 670c59e2a14161461d2133209eace82ec7aee08a
Show file tree
Hide file tree
Showing 3 changed files with 132 additions and 131 deletions.
@@ -0,0 +1 @@
*.iml
@@ -1,85 +1,85 @@
Title: Externalized Configuration

[//]: # (content copied to _user-guide_xxx)

As described [here](./configuration-files.html), Isis itself bootstraps from the `isis.properties` configuration file.
It will also read configuration from the (optional) component/implementation-specific configuration files (such as
`persistor_datanucleus.properties` or `viewer_wicket.properties`) and also (otional) component-specific configuration
files (such as `persistor.properties` or `viewer.properties`).

> By convention we put JDBC URL properties in `persistor.properties`, but they could reside in any of
> `persistor_datanucleus.properties`, `persistor.properties` or (even) `isis.properties`
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:

* Apache Isis itself

which as already discussed reads `isis.properties` and optional component-specific config files.

* [Apache Shiro](http://shiro.apache.org) (if using the Isis' [Shiro integration](../components/security/shiro/about.html) for authentication and/or authorization

which reads the `shiro.ini` file (and may read other files referenced from that file)

* [Apache log4j 1.2](http://logging.apache.org/log4j/1.2), for logging

which reads `logging.properties` file

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

## <a name="isis">Externalizing Isis' Configuration</a>

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

<context-param>
<param-name>isis.config.dir</param-name>
<param-value>location of external config directory</param-value>
</context-param>

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"
value="/usr/local/tomcat/myapp/conf/"
override="true"/>

For more detail, see the Tomcat documentation on [defining a context](http://tomcat.apache.org/tomcat-7.0-doc/config/context.html#Defining_a_context) and on [context parameters](http://tomcat.apache.org/tomcat-7.0-doc/config/context.html#Context_Parameters).

## <a name="shiro">Externalizing Shiro's Configuration</a>

If using Isis' [Shiro integration](../components/security/shiro/about.html) 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"
value="file:/usr/local/myapp/conf/shiro.ini"
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.

## <a name="log4j">Externalizing Log4j's Configuration</a>

By default Isis configures log4j to read the `logging.properties` file in the `WEB-INF` directory. This can be overridden by setting the `log4j.properties` 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/logging.properties"

Further details an be found in the [log4j documentation](https://logging.apache.org/log4j/1.2/manual.html#Example_Configurations).

> `CATALINA_OPTS` was called `TOMCAT_OPTS` in earlier versions of Tomcat.
## See also

See [JVM args](./jvm-args.html) for other JVM args and system properties that you might want to consider setting.
Title: Externalized Configuration

[//]: # (content copied to _ug_deployment_externalized-configuration)

As described [here](./configuration-files.html), Isis itself bootstraps from the `isis.properties` configuration file.
It will also read configuration from the (optional) component/implementation-specific configuration files (such as
`persistor_datanucleus.properties` or `viewer_wicket.properties`) and also (otional) component-specific configuration
files (such as `persistor.properties` or `viewer.properties`).

> By convention we put JDBC URL properties in `persistor.properties`, but they could reside in any of
> `persistor_datanucleus.properties`, `persistor.properties` or (even) `isis.properties`
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:

* Apache Isis itself

which as already discussed reads `isis.properties` and optional component-specific config files.

* [Apache Shiro](http://shiro.apache.org) (if using the Isis' [Shiro integration](../components/security/shiro/about.html) for authentication and/or authorization

which reads the `shiro.ini` file (and may read other files referenced from that file)

* [Apache log4j 1.2](http://logging.apache.org/log4j/1.2), for logging

which reads `logging.properties` file

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

## <a name="isis">Externalizing Isis' Configuration</a>

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

<context-param>
<param-name>isis.config.dir</param-name>
<param-value>location of external config directory</param-value>
</context-param>

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"
value="/usr/local/tomcat/myapp/conf/"
override="true"/>

For more detail, see the Tomcat documentation on [defining a context](http://tomcat.apache.org/tomcat-7.0-doc/config/context.html#Defining_a_context) and on [context parameters](http://tomcat.apache.org/tomcat-7.0-doc/config/context.html#Context_Parameters).

## <a name="shiro">Externalizing Shiro's Configuration</a>

If using Isis' [Shiro integration](../components/security/shiro/about.html) 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"
value="file:/usr/local/myapp/conf/shiro.ini"
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.

## <a name="log4j">Externalizing Log4j's Configuration</a>

By default Isis configures log4j to read the `logging.properties` file in the `WEB-INF` directory. This can be overridden by setting the `log4j.properties` 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/logging.properties"

Further details an be found in the [log4j documentation](https://logging.apache.org/log4j/1.2/manual.html#Example_Configurations).

> `CATALINA_OPTS` was called `TOMCAT_OPTS` in earlier versions of Tomcat.
## See also

See [JVM args](./jvm-args.html) for other JVM args and system properties that you might want to consider setting.
@@ -1,46 +1,46 @@
Title: Suggested JVM args

[//]: # (content copied to _user-guide_xxx)

The default JVM configuration will most likely not be appropriate for running Isis as a webapp. Some args that you will

<table class="table table-striped table-bordered">
<tr>
<th>Flag</th>
<th>Description</th>
</tr>
<tr>
<td>&#8209;server</td>
<td>Run the JVM in server mode, meaning that the JVM should spend more time on the optimization of the fragments of codes that are most often used (hotspots). This leads to better performance at the price of a higher overhead at startup</td>
</tr>
<tr>
<td>&#8209;Xms128m</td>
<td>Minimum heap size</td>
</tr>
<tr>
<td>&#8209;Xmx768m</td>
<td>Maximum heap size</td>
</tr>
<tr>
<td>&#8209;XX:PermSize=64m</td>
<td>Minimum perm size (for class definitions)</td>
</tr>
<tr>
<td>&#8209;XX:MaxPermSize=256m</td>
<td>Maximum perm size (for class definitions)</td>
</tr>
<tr>
<td>&#8209;XX:+DisableExplicitGC</td>
<td>Causes any explicit calls to <tt>System.gc()</tt> to be ignored. See <a href="http://stackoverflow.com/questions/12847151/setting-xxdisableexplicitgc-in-production-what-could-go-wrong">this stackoverflow</a> question.</td>
</tr>
</table>

There are also a whole bunch of GC-related flags, that you might want to explore; see this detailed [Hotspot JVM](http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html) documentation and also this [blog post](http://blog.ragozin.info/2011/09/hotspot-jvm-garbage-collection-options.html).


## Configuring in Tomcat

If using Tomcat, update the `CATALINA_OPTS` variable.

> This variable is also updated if [configuring logging to run externally](./externalized-configuration.html#log4j).
Title: Suggested JVM args

[//]: # (content copied to _ug_deployment_jvm-flags)

The default JVM configuration will most likely not be appropriate for running Isis as a webapp. Some args that you will

<table class="table table-striped table-bordered">
<tr>
<th>Flag</th>
<th>Description</th>
</tr>
<tr>
<td>&#8209;server</td>
<td>Run the JVM in server mode, meaning that the JVM should spend more time on the optimization of the fragments of codes that are most often used (hotspots). This leads to better performance at the price of a higher overhead at startup</td>
</tr>
<tr>
<td>&#8209;Xms128m</td>
<td>Minimum heap size</td>
</tr>
<tr>
<td>&#8209;Xmx768m</td>
<td>Maximum heap size</td>
</tr>
<tr>
<td>&#8209;XX:PermSize=64m</td>
<td>Minimum perm size (for class definitions)</td>
</tr>
<tr>
<td>&#8209;XX:MaxPermSize=256m</td>
<td>Maximum perm size (for class definitions)</td>
</tr>
<tr>
<td>&#8209;XX:+DisableExplicitGC</td>
<td>Causes any explicit calls to <tt>System.gc()</tt> to be ignored. See <a href="http://stackoverflow.com/questions/12847151/setting-xxdisableexplicitgc-in-production-what-could-go-wrong">this stackoverflow</a> question.</td>
</tr>
</table>

There are also a whole bunch of GC-related flags, that you might want to explore; see this detailed [Hotspot JVM](http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html) documentation and also this [blog post](http://blog.ragozin.info/2011/09/hotspot-jvm-garbage-collection-options.html).


## Configuring in Tomcat

If using Tomcat, update the `CATALINA_OPTS` variable.

> This variable is also updated if [configuring logging to run externally](./externalized-configuration.html#log4j).

0 comments on commit 670c59e

Please sign in to comment.