Guvnor uses the JCR standard for storing assets such as rules. The default implementation is Apache Jackrabbit, http://jackrabbit.apache.org. This includes an out of the box storage engine/database, which you can use as is, or configure to use an existing RDBMS if needed.
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 components.xml file in
the WEB-INF directory. This is a JBoss Seam configuration file (Seam 2 is the
framework used) which allows various parts of the system to be customized. When you have located the
components.xml file, you should see something like the following:
<component name="repositoryConfiguration">
<!-- JackRabbit -->
<property name="properties">
<key>org.drools.repository.configurator</key><value>org.drools.repository.jackrabbit.JackrabbitRepositoryConfigurator</value>
<!-- the root directory for the repo storage the directory must exist. -->
<!-- <key>repository.root.directory</key><value>/opt/yourpath</value> -->
</property>
...
</component>
Find the component with a name of repositoryConfiguration 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 components.xml you can
simply move the repository.xml AND the repository directory to the new
location that you set in the components.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.
Repository Configuration Manager includes template configuration files for many external RDBMS types. The first thing you have to do is the select the RDBMS type from the dropdown menu and select if you are using JNDI to look up your data source or not.
If you opt to use JNDI, you have to enter the JNDI name configured in your deployed data source. Otherwise you need to enter your RDBMS information.
At this point you are ready to generate your repository.xml give your RDBMS information.
Click on the "Generate repository config" button.
You can download the generated repository.xml file by clicking the "Save Configuration"
button, or copy/paste the generated text manually. Replace your existing repository.xml with
the generated one and restart Guvnor for the changes to get picked up.
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.