By default, Orbeon Forms ships with an embedded eXist database. For production, this is not an ideal setup and it is better to have a separate eXist database, whether:
a separate WAR file running the same servlet container
or a completely separate eXist instance running in a separate container
Here we look at how to deploy a separate eXist WAR file (the first option).
NOTE: Since Orbeon Forms 4.0, the embedded eXist database is secured by a token mechanism, which only allows accesses internal to Orbeon Forms. Follow the instructions on this page if you need to setup a secure, separate eXist database which can be accessed from outside Orbeon Forms, or setup a completely separate eXist instance.
eXist as of version 1.4 no longer ships with a separate WAR file, but it is reasonably easy to create one.
Assume the following:
you are running running on a Unix system
you are running as user
acme with home in
download eXist 1.4
run the eXist installer in headless mode
java -jar eXist-setup-1.4.0-rev10440.jar -p /home/acme/exist-tmp
supply an administrator password when asked to do so
repackage eXist (see )
if you have limited memory, change
~/exist-tmp/build.sh to set
build the WAR file
this produces a packed WAR file
unzip the contents of eXist WAR under
create a symlink to that WAR if you want
ln -s exist-war-1.4.0-rev10440 exist-war
Instead of storing the eXist data files under the eXist WAR, specify a separate location, for example:
To do this, modify the
journal-dir attributes in
<db-connection files="/home/acme/exist-data" ...><recovery journal-dir="/home/acme/exist-data" ...>
The benefit of this is this is that upgrading the eXist WAR file will be easier: you can:
leave the data in place
build/install a new eXist WAR
exist-war symbolic link
update again the eXist configuration to point to your data
When deploying eXist as a WAR file, it will run using the Unix user of the servlet container. Often, this is a user called e.g.
tomcat. You need to make sure that user can write:
the eXist data:
chown -R tomcat:tomcat /home/acme/exist-data
chown -R tomcat:tomcat /home/acme/exist-war/WEB-INF/logs/
To do so, you can use the eXist database administration tool:
orbeon (you can pick your own user name)
Password: pick a proper password for the
/db/orbeon is a reasonable choice
Create a group, for example
orbeon, and assign it to the
By default, eXist allows everybody to read newly created collections and resources. This might not be desirable. To protect Form Runner resources from other users, uncomment and set the following configuration in
<default-permissions collection="0740" resource="0740" />
This will cause new collections and resources to be only fully accessible through user
NOTE: With this setting, other users in the group
orbeon can read Form Runner resources and collections too, although this is not currently useful.
With Orbeon Forms 3.9 and 4.x Form Runner uses the Lucene-based full-text index. Here too you need to store a
collection.xconf file, but it contains a different configuration:
<collection xmlns="http://exist-db.org/collection-config/1.0"><index><!-- Disable the standard full text index --><fulltext default="none" attributes="no"/><!-- Lucene index is configured below --><lucene><analyzer class="org.apache.lucene.analysis.standard.StandardAnalyzer"/><!-- We want to index the content of all form elements --><text match="//*"/></lucene></index></collection>
You typically use the eXist admin client to store this configuration under collection:
See also the latest version of this file on GitHub.
NOTE: Without this configuration, free-text search in the Form Runner summary page won't work.
The last step is to tell Form Runner how to connect to eXist. Set the following property in the Orbeon
properties-local.xml file. With Orbeon Forms 4.0:
The eXist user you picked above is
The eXist password you picked above is
secret (don't actually use "
secret", use your own unique password!)
Your servlet container is deployed on port 8080
The eXist WAR is deployed under path
Your want to put your Form Runner documents under collection
NOTE: the password is available in clear in properties-local.xml. You must make sure that there is no unauthorized access to that file.
After this setup, your file hierarchy looks like this:
/home/acme/ -> home where eXist is installedexist-war/ -> eXist WAR fileWEB-INF/logs/ -> eXist logs writable by tomcat userexist-data/ -> where your eXist data is stored, writable by tomcat user
only the eXist administrator can modify the eXist configuration
data created by Form Runner is not readable except by
the eXist administrator