You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2014/03/17 23:30:13 UTC
svn commit: r1578638 - in /isis/site/trunk/content: documentation.md
reference/configuration-files.md reference/deployment-type.md
reference/externalized-configuration.md reference/jvm-args.md
Author: danhaywood
Date: Mon Mar 17 22:30:12 2014
New Revision: 1578638
URL: http://svn.apache.org/r1578638
Log:
configuration files
Added:
isis/site/trunk/content/reference/externalized-configuration.md
isis/site/trunk/content/reference/jvm-args.md
Modified:
isis/site/trunk/content/documentation.md
isis/site/trunk/content/reference/configuration-files.md
isis/site/trunk/content/reference/deployment-type.md
Modified: isis/site/trunk/content/documentation.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/documentation.md?rev=1578638&r1=1578637&r2=1578638&view=diff
==============================================================================
--- isis/site/trunk/content/documentation.md (original)
+++ isis/site/trunk/content/documentation.md Mon Mar 17 22:30:12 2014
@@ -326,6 +326,7 @@ For both:
#### <a name="reference-config">Config</a>
* [Configuration Files](./reference/configuration-files.html)
+* [Externalized Configuration](./reference/externalized-configuration.html)
#### <a name="reference-non-ui-execution">Non-UI execution</a>
Modified: isis/site/trunk/content/reference/configuration-files.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/reference/configuration-files.md?rev=1578638&r1=1578637&r2=1578638&view=diff
==============================================================================
--- isis/site/trunk/content/reference/configuration-files.md (original)
+++ isis/site/trunk/content/reference/configuration-files.md Mon Mar 17 22:30:12 2014
@@ -1,79 +1,86 @@
Title: Configuration Files
-Isis has one mandatory configuration file, `isis.properties`. For the webapp viewers, this typically lives alongside the `web.xml` file in the `WEB-INF` directory. If necessary, though, it can be configured to live outside this directory; this is discussed later on in this article.
+Isis has one mandatory configuration file, `isis.properties`. For the webapp viewers, this typically lives alongside the `web.xml` file in the `WEB-INF` directory.
-In addition to the `isis.properties` file, Isis will also read from a number of supplementary configuration files. For example:
+In addition, Isis will also read from a number of supplementary configuration files (if present), for each of the configured components. For example:
-* if the JDO (DataNucleus) objectstore is configured, then Isis will search for `persistor_datanucleus.proeprties`.
+* if the JDO (DataNucleus) objectstore (aka persistor) is configured, then Isis will search for `persistor_datanucleus.properties`. Isis will also read from `persistor.properties`
+* if the Shiro authentication has been configured, it will search for `authentication_shiro.properties`. Isis will also read from `authentication.properties`.
-* Or, if the Shiro authentication has been configured, it will search for `authentication_shiro.properties`.
+This approach allows configuration to be partitioned by component.
-This approach allows configuration to be partitioned by component. To restate though, this is not mandatory: you can just use `isis.properties` for all configuration if you wish.
+> It is also possible to externalize all configuration files so that they reside outside of `WEB-INF` directory; this is discussed [here](./externalized-configuration.html).
-### Specifying Components
+## Specifying Components
A running Isis instance requires a persistor (aka objectstore), the authentication mechanism, the authorization mechanism, and a user profile store. It also requires some sort of viewer or viewers.
-The persistor, authentication, authorization and profilestore are specified in the `isis.properties` file. For example, this is the configuration of the [simple](../intro/getting-started/simple-archetype.html) archetype:
+The objectstore, authentication, authorization and profilestore are specified in the `isis.properties` file. For example, this is the configuration of the [simple](../intro/getting-started/simple-archetype.html) archetype:
-<pre>
-isis.persistor=datanucleus
-isis.authentication=shiro
-isis.authorization=shiro
-isis.user-profile-store=in-memory
-</pre>
+ isis.persistor=datanucleus
+ isis.authentication=shiro
+ isis.authorization=shiro
+ isis.user-profile-store=in-memory
The available values are registered in [installer-registry.properties](https://raw.github.com/apache/isis/master/core/runtime/src/main/resources/org/apache/isis/core/runtime/installer-registry.properties); alternatively the fully qualified class name can be specified. In either case the appropriate component must also (of course) be added as a dependency to the `pom.xml` files.
The viewer is *not* specified in the `isis.properties` file; rather it is implied by the configuration of `WEB-INF/web.xml` file. The archetypes are a good point of reference for the required servlet context listeners and servlets; every viewer has its own requirements.
-Some of the viewers have their own configuration properties. These can also be moved out into their supplementary config files, provided that an additional entry is made in the `web.xml` file. For example, to specify that the Wicket viewer and Restful Objects viewer config files should be read, add the following:
+## Componentized configuration Files by component
-<pre>
-<context-param>
- <param-name>isis.viewers</param-name>
- <param-value>wicket,restfulobjects</param-value>
-</context-param>
-</pre>
-
-This will cause Isis to search and read for `viewer_wicket.properties` and `viewer_restfulobjects.properties`.
-
-(Note: this is only supported for the Wicket viewer for 1.2.0 on, see [ISIS-342](https://issues.apache.org/jira/browse/ISIS-342))
-
-### Specifying an external configuration directory
-
-As noted above, by default Isis will look for configuration files in the `WEB-INF` directory. If you wish to vary the configuration by environment (eg systest vs production), then this can be altered by specifying the `isis.config.dir` context parameter.
-
-If the external configuration directory will change from one environment to another, then specify the context parameter according to the documentation of your chosen servlet container.
-
-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:
-
-<pre>
-<Parameter name="isis.config.dir"
- value="/usr/local/tomcat/conf/"
- override="true"/>
-</pre>
-
-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).
-
-If the external configuration directory is fixed for all environments, then you can specify within the `web.xml` itself:
-
-<pre>
-<context-param>
- <param-name>isis.config.dir</param-name>
- <param-value>location of external config directory</param-value>
-</context-param>
-</pre>
-
-
-
-###Shiro
-
-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.
+As noted in the introduction, the configuration can optionally be broken out by component and also component implementation.
+This is also supported for the configured viewer(s). However, because the configured viewer(s) is/are not listed in `isis.properties`, an additional hint is required in the `web.xml` file to tell Isis which viewers are in use.
+For example, to specify that the Wicket viewer and Restful Objects viewers are configured, specify:
+ <context-param>
+ <param-name>isis.viewers</param-name>
+ <param-value>wicket,restfulobjects</param-value>
+ </context-param>
+
+The table below summarizes the additional configuration files that are searched for the most commonly configured components:
+
+<table class="table table-striped table-bordered table-condensed">
+<tr>
+ <th>Component type</th>
+ <th>Component implementation</th>
+ <th>Additional configuration files</th>
+</tr>
+<tr>
+ <td>Object Store</td>
+ <td>JDO (DataNucleus)</td>
+ <td>persistor_datanucleus.properties<br/>
+persistor.properties</td>
+</tr>
+<tr>
+ <td>Authentication</td>
+ <td>Shiro</td>
+ <td>authentication_shiro.properties<br/>
+authentication.properties</td>
+</tr>
+<tr>
+ <td>Authorization</td>
+ <td>Shiro</td>
+ <td>authorization_shiro.properties<br/>
+authorization.properties</td>
+</tr>
+<tr>
+ <td>Viewer</td>
+ <td>Wicket</td>
+ <td>viewer_wicket.properties<br/>
+viewer.properties</td>
+</tr>
+<tr>
+ <td>Viewer</td>
+ <td>Restful Objects</td>
+ <td>viewer_restfulobjects.properties<br/>
+viewer.properties</td>
+</tr>
+<tr>
+ <td>Profile Store</td>
+ <td>In-memory</td>
+ <td>user-profile-store_in-memory.properties<br/>
+user-profile-store.properties</td>
+</tr>
+</table>
Modified: isis/site/trunk/content/reference/deployment-type.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/reference/deployment-type.md?rev=1578638&r1=1578637&r2=1578638&view=diff
==============================================================================
--- isis/site/trunk/content/reference/deployment-type.md (original)
+++ isis/site/trunk/content/reference/deployment-type.md Mon Mar 17 22:30:12 2014
@@ -26,7 +26,7 @@ EXPLORATION<br/>
UTILITY</td>
<td>Visible</td>
<td>Not visible</td>
- </tr>
+</tr>
<tr>
<td>PROTOTYPING</td>
<td>SERVER_PROTOTYPE<br/>
Added: isis/site/trunk/content/reference/externalized-configuration.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/reference/externalized-configuration.md?rev=1578638&view=auto
==============================================================================
--- isis/site/trunk/content/reference/externalized-configuration.md (added)
+++ isis/site/trunk/content/reference/externalized-configuration.md Mon Mar 17 22:30:12 2014
@@ -0,0 +1,73 @@
+Title: Externalized Configuration
+
+As described [here](./configuration-files.html), Isis itself bootstraps from the (mandatory) `isis.properties` configuration files and also (optional) component-specific configuration files (such as `persistor_datanucleus.properties` or `viewer_wicket.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>
+
+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 accepts any URL, not only a filesystem directory.
+
+
+## <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=-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](./suggested-jvm-args.html) for other JVM args and system properties that you might want to consider setting.
Added: isis/site/trunk/content/reference/jvm-args.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/reference/jvm-args.md?rev=1578638&view=auto
==============================================================================
--- isis/site/trunk/content/reference/jvm-args.md (added)
+++ isis/site/trunk/content/reference/jvm-args.md Mon Mar 17 22:30:12 2014
@@ -0,0 +1,44 @@
+Title: Suggested JVM args
+
+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 table-condensed">
+<tr>
+ <th>Flag</th>
+ <th>Description</th>
+</tr>
+<tr>
+ <td>-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>-Xms128m</td>
+ <td></td>
+</tr>
+<tr>
+ <td>-Xmx768m</td>
+ <td></td>
+</tr>
+<tr>
+ <td>-XX:PermSize=64m</td>
+ <td></td>
+</tr>
+<tr>
+ <td>-XX:MaxPermSize=256m</td>
+ <td></td>
+</tr>
+<tr>
+ <td>-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).
+