Assuming you are using on of the JBoss platforms, running Guvnor for the first time will create a database in the bin/ directory of the application server. There you will find the default Jackrabbit configuration file, namely repository.xml, and a repository directory which contains your repository data. Both of these are created automatically for you.

The location of the data store should be a secure location, that is backed up. The default location may not be suitable for this, so the easiest way is to set a more suitable location. If you want to change this, please make sure you have stopped Guvnor (i.e. stopped the app server or un-deployed the application).

To change the location, unzip the Guvnor WAR file, and locate the beans.xml file in the WEB-INF/classes/META-INF directory. This is a JBoss Seam configuration file (Seam 3 is the framework used) which allows various parts of the system to be customized. When you have located the beans.xml file, you should see something like the following:

  <guvnorRepository:GuvnorBootstrapConfiguration>

    <s:modifies/>



    <!-- JackRabbit  -->

    <guvnorRepository:properties>

      <s:entry><s:key>org.drools.repository.configurator</s:key><s:value>org.drools.repository.jackrabbit.JackrabbitRepositoryConfigurator</s:value></s:entry>

      <!--  the root directory for the repo storage the directory must exist. -->

      <!--<s:entry><s:key>repository.root.directory</s:key><s:value>/opt/yourpath</s:value></s:entry>-->

    </guvnorRepository:properties>



    ...

  </guvnorRepository:GuvnorBootstrapConfiguration>

Find the component with a name of GuvnorBootstrapConfiguration and its section for JackRabbit configuration, then the key property with the name of repository.root.directory.

If you un-comment this key element (as in the example above it is commented out), you can set whatever file-system path you need for the repository data to be stored in. You can also use this to move the repository around. In that case, when you have set the location in the beans.xml you can simply move the repository.xml AND the repository directory to the new location that you set in the beans.xml.

If there is no repository.xml configuration file, or the repository directory at the location specified (or in the default location) then Guvnor will create new empty ones.

There are many more options which can be configured in the repository.xml, but for the most part, it is not recommended to change the defaults.

In some cases it may be a requirement that you use an external RDBMS, such as Oracle, MySQL, or Microsoft SQL Server as the data store - this is permitted and recommended as storing your repository data in an external RDBMS is much more reliable than the default file-system storage option. The JackRabbit repository.xml file contains the information where your repository data is stored, so changes to this file are necessary for RDBMS setup. You have two options to make changes to repository.xml, namely make all changes manually, or use the Guvnor Repository Configuration Manager.

If you opt for the manual configuration, the easiest thing to do is to start up Guvnor with defaults (or with a suitable repository.root.directory directory as specified above) to let it generate the default repository.xml. Locate the repository.xml file that was generated, and open it - it will be annotated with comments describing many of the different options. From here on, you will need to know a little about Jackrabbit Persistence managers, http://wiki.apache.org/jackrabbit/PersistenceManagerFAQ. There are a few persistence managers, some are database specific (eg Oracle). There is a SimpleDBPersistenceManager which works with any database that supports JDBC - you also specify the database type, so it uses the specific DDL to create the table structure (all major databases are supported).After you have added your configuraiton options, start the Guvnor application again. Guvnor will then create the database tables the first time it is started up if it is running against a fresh (empty) RDBMS - so its important to note that the user credentials supplied have permissions to create tables (at least initially, on first run, after that they could be locked down).

Using the Repository Configuration Manager in Guvnor is often a lot easier and a less error-prone options to make the necessary configuration changes in repository.xml. With Guvnor application running, select the Administration tab in the left-hand-side navigation bar, then select the Repository Configuration link.

Figure 12.1. Finding the Repository Configuration Manager in the Administration section

Figure 12.2. Select RDBMS type

Figure 12.3. RDBMS information

Figure 12.4. Generated repository.xml

Jackrabbit has a separate storage area for version storage (as over time, the number of old versions will increase, yet it should not slow down the performance of the main data store). The version storage also has its own persistence manage configuration in the repository.xml, but for most purposes you can use the same database as the main storage (just with a different schema object prefix - ie in your database, all the version data will be prefixed with version_ but otherwise in the same tablespace). See the repository.xml for more details of this.

Lucene is used to provide indexing across the semi structured data, and across versions. This indexing is generally best stored on a filesystem, local to Guvnor (as per the default in the repository.xml) - in most cases the default is fine.