= Proposal title =

|| '''Date''' || 2011/05/25 ||
|| '''Contact(s)''' || Jesse Eichar (Camptocamp SA)||
|| '''Last edited''' || ||
|| '''Status''' || Motion passed ||
|| '''Assigned to release''' || 2.7.0 ||
|| '''Resources''' || Available ||
|| '''Ticket #''' || #513 ||

== Overview ==

In order to permit deployment of a Geonetwork instance to multiple environments and assist in development this proposal adds the ability to configure geonetwork for multiple target deployment platforms (for example, test and production) with a minimum of duplication and allow configuration selection to be chosen via System properties or !ServletConfig/Context parameters.  

=== Proposal Type ===
 * '''Module''': Jeeves

=== Links ===
 * '''Documents'''
 * '''Email discussions''':
 * '''Other wiki discussions''':

=== Voting History ===
 * Vote proposed by Jesse Eichar on 31 May 2011, result was +1 Simon and Jeroen, +0 Francois.

----

== Motivations ==

In many organizations that deploy geonetwork instances geonetwork needs to be deployed in several different environments.  For example if one is making a customized geonetwork one might have a test server and a production server.  Obviously they cannot share the same resources so the configurations of the two servers are likely very similar but with a few key differences.  

Currently you essentially need different configurations depending on which environment you are deploying to.  The pain can be somewhat alleviate by extracting the changes into separate files and using include tags to import them.  However this can require fairly substantial changes to the default geonetwork configuration files and if one is attempting to follow the Geonetwork development it can mean conflicts with the geonetwork configuration files when merging in changes from a new version of Geonetwork.  In addition there are certain types of changes one may want that cannot be accommodated by using the import strategy.

== Proposal == 
As such I propose a new method for handling multiple deployment platforms.  The standard configuration files contain the default settings and multiple override configurations can be defined to override certain parts of those defaults.  The override that is applied can be selected via one of System properties, !ServletConfig initial parameters or !ServletContext initial parameters. So depending on the server/environment where the geonetwork is deployed a different configuration can be selected with minimal duplication of configuration.

The parameter/property that is checked for the definition of the override file is '''jeeves.configuration.overrides.file'''.  If the property is not found then the no overrides are applied to the default configuration.


The following is an example of a override file:
{{{
#!xml
<overrides>
    <!-- The logging section allows logging configuration files to be specified -->
    <!-- At the moment only property based configuration files are supported -->
    <!-- There may be multiple configuration files -->
    <!-- The properties are loaded in order and subsequent files will override -->
    <!-- properties previously loaded.  This allows one to have shared configuration in -->
    <!-- one log file and more specific configuration in other files -->
    <logging>
        <logFile>logfile1.properties</logFile>
        <logFile>logfile2.properties</logFile>
    </logging>
     <!-- properties allow some properties to be defined that will be substituted -->
     <!-- into text or attributes where ${property} is the substitution pattern -->
     <!-- The properties can reference other properties -->
     <properties>
         <fr>fr</fr>
         <lang>${fr}</lang>
         <host>localhost</host>
         <enabled>true</enabled>
         <dir>xml</dir>
     </properties>
     <!-- In this version only the file name is considered not the path.  -->
     <!-- So case conf1/config.xml and conf2/config.xml cannot be handled -->
     <file name="config.xml">
         <!-- This example will update the file attribute of the xml element with the name attribute 'countries' -->
         <replaceAtt xpath="default/gui/xml[@name = 'countries']" attName="file" value="${dir}/europeanCountries.xml"/>
         <!-- if there is no value then the attribute is removed -->
         <replaceAtt xpath="default/gui" attName="removeAtt"/>
         <!-- If the attribute does not exist it is added -->
         <replaceAtt xpath="default/gui" attName="newAtt" value="newValue"/>

         <!-- This example will replace all the xml in resources with the contained xml -->
         <replaceXML xpath="resources">
           <resource enabled="${enabled}">
             <name>main-db</name>
             <provider>jeeves.resources.dbms.DbmsPool</provider>
              <config>
                  <user>admin</user>
                  <password>admin</password>
                  <driver>oracle.jdbc.driver.OracleDriver</driver>
                  <!-- ${host} will be updated to be local host -->
                  <url>jdbc:oracle:thin:@${host}:1521:fs</url>
                  <poolSize>10</poolSize>
              </config>
           </resource>
         </replaceXML>
         <!-- This example simple replaces the text of an element -->
         <replaceText xpath="default/language">${lang}</replaceText>
         <!-- This examples shows how only the text is replaced not the nodes -->
         <replaceText xpath="default/gui">ExtraText</replaceText>
         <!-- append xml as a child to a section (If xpath == "" then that indicates the root of the document),
              this case adds nodes to the root document -->
         <addXML xpath=""><newNode/></addXML>
         <!-- append xml as a child to a section, this case adds nodes to the root document -->
         <addXML xpath="default/gui"><newNode2/></addXML>
         <!-- remove a single node -->
         <removeXML xpath="default/gui/xml[@name = countries2]"/>
         <!-- remove all matching nodes -->
         <removeXML xpath="*//toRemove"/>
     </file>
         <file name="config2.xml">
         <replaceAtt xpath="default/gui/xml[@name = 'countries']" attName="file" value="${dir}/other.xml"/>
         <replaceText xpath="default/language">de</replaceText>
     </file>
</overrides>
}}}

As this example indicates the primary tags of interest are:
        logging - defines the log files to use as log4j configuration files
	properties - defines common properties throughout the override
	file - defines the file the override segment applies to
	replaceAtt - defines a override that updates an attribute of a particular node
	replaceXML - defines a override that replaces all children of a particular node
	replaceText - defines a override that sets the Text of a particular node
	addXML - defines a override that add xml as children of a given node
	removeXML - defines a override that removes XML from a node


=== Backwards Compatibility Issues ===

100% backwards compatible

=== New libraries added ===
No new libraries.

== Risks ==

== Participants ==