Jackrabbit on Tomcat6 with JNDI and PostgreSQL

Installation

Install tomcat and postgresql on your system and verify they are working correctly. On Debian/Ubuntu development systems you can install both with "apt-get". Be aware that many production sites prefer to install all server software manually.

(Sidenote: it is a considered good practice to use a separate partition for each service's data on a production server, e.g., for /var/lib/postgresql/8.3 and /var/lib/tomcat6. This makes it easier to perform specialized backups, migrate the data from one server to another, etc. There's little cost to this if you use Linux Logical Virtual Modules (lvm), and it's not really necessary on a development server.)

Install the jackrabbit .war file. If the system will be a dedicated jackrabbit server you can rename the jackrabbit-1.5.4.war file to ROOT.war and have it unpacked as ROOT. This means you can access the jackrabbit instance as http://example.com:8080/ instead of http://example.com:8080/jackrabbit-1.5.4/.

Create a ${catalina.home}/common directory and copy jcr-1.0.jar to it. Edit ${catalina.home}/conf/catalina.properties and add ${catalina.home}/common,${catalina.home}/common/*.jar to the common.loader entry. This allows us to add libraries to the server without mixing them with the standard tomcat libraries - something that's extremely helpful when things stop working and you aren't sure which library is the culprit!

Finally, edit /etc/default/tomcat6 to add -Djava.rmi.server.hostname=hostname to CATALINA_OPTS, where you have changed 'hostname' to a public network interface. If you don't do this the RMI library will probably pick something weird like 127.0.1.1 (NOT 127.0.0.1) and you'll spend hours knocking head-shaped holes in the wall. You will need to use a public network interface to allow others to connect to the RMI server.

Basic Configuration

• Create a user and database for jackrabbit. (see: createuser, createdb).
  
• Create an external directory for the jackrabbit files. By default it puts them somewhere in the tomcat tree (under bin?), but it's a good practice to put that someplace external from tomcat since you may want to access the repository later via a mechanism other than the tomcat webapp. I put it under /srv/jackrabbit.
  
• Copy the bootstrap.properties and repository.xml files from /WEB-INF/templates to /srv/jackrabbit.
  
• Edit /WEB-INF/web.xml and change the value of all bootstrap-config parameters to /srv/jackrabbit/bootstrap.properties.
  
• Edit /srv/jackrabbit/bootstrap.properties so repository.home=/srv/jackrabbit and repository.conf=/srv/jackrabbit/repository.xml.
  
• Edit /srv/jackrabbit/repository.xml so all FileSystem stanzas use org.apache.jackrabbit.core.fs.db.DbFileSystem and all PersistenceManager stanzas use org.apache.jackrabbit.core.persistence.bundle.PostgreSQLPersistenceManager. Set schema to postgresql in each stanza's configuration.
  
• The DataStore stanza should use org.apache.jackrabbit.core.data.db.DbDataStore with a databaseType (not schema) of postgresql.
  
• Set all schemaObjectPrefix as described in other wiki entries. (I use FS_,

FS_WSP${wsp.name}, _PM_WSP${wsp.name}_, etc.)

• In all of these stanzas set the driver to org.postgresql.Driver, the url to jdbc:postgresql://host:5432/dbname, and the user and password as appropriate.
  

Restart tomcat. The database should now contain about 20 tables, and more importantly we know that the basic infrastructure is in place and we just need to refine it to use JNDI.

JNDI Configuration

• Copy your postgresql jdbc jar, postgresql-xxx.jar, to ${catalina.home}/common.
  
• If you unpacked the jackrabbit .war file as ROOT, edit ${catalina.home}/conf/Catalina/localhost/ROOT.xml. If not, edit conf/Catalina/localhost/jackrabbit-1.5.4.xml or whatever you named the webapp. This file may not yet exist. You want root to own this file, not the tomcat user, so prevent it from being overridden when redeploying the jackrabbit webapp.
  
• Add the following Resource stanza to the Context stanza:
  

<Resource name="jdbc/jcr"
auth="container"
type="javax.sql.DataSource"
driverClassName="org.postgresql.Driver"
maxActive="20"
maxIdle="10"
maxWait="-1"
url="jdbc:postgresql://localhost:5432/jcr"
username="jcr"
password="jackrabbit"
validationQuery="select 1"/>

• Add the following stanza to the bottom of your web.xml file:
  

<resource-ref>
<description>JCR database connection</description>
<res-ref-name>jdbc/jcr</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>

• Edit the repository.xml file so that all driver are set to javax.naming.InitialContext,

all url are set to java:comp/env/jdbc/jcr, and all user and password entries are dropped.

• Restart tomcat. Check the logs for errors. Jackrabbit should now be running using the JNDI-specified database.
  

Changing Databases

At this point it should be trivial to change the database: edit ROOT.xml and restart tomcat. You'll want to back up and restore the jackrabbit instance as you do this.