Production Deployment Guide for
all
SQL Power Enterprise Servers
(including Architect Enterprise & Wabit
Enterprise Servers)
Introduction
This document contains guidelines about the deployment of
SQL Power enterprise software in a production environment. It
will cover the installation and configuration of the server
components. It does not cover however the installation and
usage of the client components. For more details about the client
components, please refer to our online FAQ or our
various getting started guides:
Deployment
SQL Power enterprise products are distributed as a web
application archive (war). They need to be deployed in a Java
application server. Because they are application server
agnostic, you can choose the application server you prefer or
are more familiar with; whether it's Apache Tomcat, JBoss's
Application Server, Sun Glassfish or any other Servlet 2.5
compatible application server. The exact method of deploying
our WAR bundle depends on the application server you choose,
but this typically means that you need to copy the file to the
right directory.
WAR files are in fact simple .zip files with a special
extension. They can be expanded and their contents modified at
will, and then re-compressed. Most application servers support
both the deployment of WAR files and directory structures, so
you might prefer to decompress the WAR file to facilitate the
customization of the contents of the application files.
Data Persistence
SQL Power Enterprise Software needs to store the shared
repository data in a physical location. This section will
explain the default behavior in order to persist the data, and
how to customize this behavior to suit your needs in a
production environment.
Default Data Persistence Behaviour
Our Enterprise Software uses Apache Jackrabbit 1.6 to store
and organize the repository data. When you first start an
application, a directory in the user's home directory called
'[product name]-enterprise-repository' gets created. This
folder contains:
- Repository Metadata
The repository metadata consists of files called
'workspace.xml' and are automatically generated by Jackrabbit
when you create new projects on the server.
- Search Indexes
The search indexes are generated by Apache Lucene, a library
used by Jackrabbit which allows it to perform fast searches
through your content repository. Those indexes must reside on
the local file system and can be deleted between server
restarts, since they are generated every time an application
starts.
- Repository Data
The repository data is an Apache Derby database. Apache
Derby is a file-based database and will persist the
repository contents directly on the hard drive.
Customizing the Default Data Persistence Behavior
The defaults are all defined in a file called
'repository.xml' located in the applications 'WEB-INF/classes/'
directory, inside the web archive file of the application. In
order to modify this file, you might need to extract the WAR
file contents, using any .zip compliant archiving software, and
edit it's contents for custom deployments.
Customizing the Repository Metadata Location
In the repository.xml file, look for the XML element named
Workspaces. It looks like this:
<Workspaces rootPath="${rep.home}/workspaces"
defaultWorkspace="system"/>
The metadata files must be stored on a OS file system. In
order to modify their location, do not modify the rootPath
parameter directly. The Jackrabbit variable named rep.home can
be set in a different configuration file. This configuration
file is named web.xml and can be found inside the web
application archive in the WEB-INF directory. Open the web.xml
file and look for the following:
<context-param>
<param-name>repositoryHome</param-name>
<param-value>${user.home}/[product
name]-enterprise-repository</param-value>
</context-param>
By setting the param-value element to a different value, you
will effectively change the location of the repository metadata
files. This might also impact the location of the search
indexes, since they refer to either the rep.home variable or
the wsp.home variable, the latter being dependent by default on
the rep.home value. Should you decide to customize the way
Jackrabbit stores its files, we suggest experimenting with
different setups and deciding which is more practical from a
maintenance point of view. As a rule of thumb, try to keep all
the file system metdata files in a unified location for easier
backups and recovery.
Customizing the Search Indexes Location
In the repository.xml file, search for XML elements named
SearchIndex. Those elements look like this:
<SearchIndex
class="org.apache.jackrabbit.core.query.lucene.SearchIndex">
<param name="path"
value="${wsp.home}/index"/>
<param name="extractorPoolSize"
value="2"/>
<param name="supportHighlighting"
value="true"/>
</SearchIndex>
There should be two of those elements in the repository.xml
file. One of them is nested in a Workspace element, and defines
the indexing behavior of each particular workspace. The second
block is nested in the Repository root element and defines the
indexing behavior of the repository metadata. These two blocks
are independent and can be configured differently.
In order to modify the location of the temporary indexing
files, you should modify the parameter names path and point it
to the desired location. Keep in mind that the SearchIndex
element (which is nested under the Workspace element) is to be
configured carefully, since each workspace needs it's own
temporary index files location. Setting this parameter without
using the Jackrabbit supplied variables in the path might
result in unstable behaviour. For more information about the
configuration and optimization of the search indexes, please
refer to Jackrabbit's
documentation on the subject.
Customizing the Repository Data Location
SQL Power Enterprise Software stores all the repository data
on the file system by default. It uses Apache Derby to manage
these files contents. Jackrabbit is extremely flexible in its
configuration and supports many different configuration
options, whether you prefer a file system based persistence
system or a database based one. This section will discuss the
basics of what is required in order to store the repository
data in a relational database. As an example, we will
demonstrate how to persist the repository data in a relational
database.
In a nutshell, Jackrabbit uses FileSystems and
PersistenceManagers to persist it's repository data. In order
to switch from a file-based solution to a database-backed one,
we will edit the repository.xml file and modify the FileSystem
and PersistenceManager XML elements. There are more than one of
each of those elements in the repository configuration file, so
make sure that you modify all their occurrences.
Configuring the FileSystems
Early versions on Jackrabbit were designed to abstract their
persistence mechanism using a virtual file system layer defined
in the
FileSystem interface. This low-level approach didn't work
that well in practice, and so most of the persistence
abstraction is now handled at a higher level. However, certain
parts of Jackrabbit still use this file system abstraction.
A virtual file system is configured in a FileSystem XML
configuration element. See the main file system implementations
LocalFileSystem,
DatabaseFileSystem (including subclasses), and
MemoryFileSystem for the available options. The default
behavior is to use the LocalFileSystem implementation that
simply maps abstract file system accesses to the specified
directory within the native file system.
Should you decide to use the database-backed FileSystem
configurations, your repository.xml file's FileSystem elements
would look similar to this, for a MySQL database backend:
<FileSystem
class="org.apache.jackrabbit.core.fs.db.DbFileSystem">
<param name="driver"
value="com.mysql.jdbc.Driver"/>
<param name="url"
value="jdbc:mysql://localhost:3306/database_name?autoReconnect=true"/>
<param name="user" value=""/>
<param name="password" value=""/>
<param name="schema" value="mysql"/>
...
</FileSystem>
Configuring the PersistenceManagers
The PMs are internal Jackrabbit components that handle the
persistent storage of content nodes and properties. Property
values are also stored in the persistence manager, with the
exception of large binary values (those are usually kept in the
DataStore).
Each workspace of a Jackrabbit content repository uses a
separate persistence manager to store the content in that
workspace. Also, the Jackrabbit version handler uses a separate
persistence manager.
The persistence manager implementations are configured using
the PersistenceManager XML element nested within the Workspace
XML element (and the instantiated workspace configuration
files) and the Versioning XML element. The layout of a
PersistenceManager configuration element is shown below:
<PersistenceManager class="...">
<param name="..." value="..."/>
...
</PersistenceManager>
The class attribute of the PersistenceManager element
contains the fully-qualified class name of the persistence
manager implementation class. String properties can be assigned
using the param elements according to the JavaBean conventions.
Should you decide to use MySQL as your database persistence
backend, your configuration would look something like this:
<PersistenceManager class="org.apache.jackrabbit.core.persistence.db.SimpleDbPersistenceManager">
<param name="driver" value="com.mysql.jdbc.Driver"/>
<param name="url" value="jdbc:mysql://localhost:3306/database_name?autoReconnect=true"/>
<param name="user" value=""/>
<param name="password" value=""/>
<param name="schema" value="mysql"/>
<param name="externalBLOBs" value="false"/>
...
</PersistenceManager>
For more details on the configuration of the PersistenceManagers, please refer to these handy resources:
About File-based Data Stores on Linux
Some file-based databases (such as Derby) require a high number of
opened files at the same time. This usually doesn't present an issue,
except on some Linux distributions. Ubuntu, for example, limits the number of
opened files per process to 1024. It is therefore necessary to augment the
maximum number of file handles per process in certain environments.
Please refer to your OS-specific documentation to obtain instructions on
how to augment the maximum number of opened files.
Specifically for Ubuntu and similar Linux distributions, you need
to add two lines to /etc/security/limits.conf or edit them if they are
already in there. Add/edit the following two lines...
username soft nofile x
username hard nofile x
...where x is a positive multiple of 2, such as 32768. (The Ubuntu default of 1024
is insufficient for SQL Power Architect Enterprise Edition, but increasing the value to 32768
eliminates the problem.)
Backups & Restoring
In order to perform security backups, we recommend you perform a low-level copy of the repository contents. The items you must make security copies of are:
- The directory defined by the Workspaces XML element in your repository.xml configuration file
This directory will contain all workspace access information and metadata. You should make backup copies of the contents of this directory.
- The search indexes files
Although these files get automatically generated upon startup, we strongly recommend making security backups of them as well, since in the absence of these, Jackrabbit must re-index the entire contents of your repository.
- The repository data
If your repository data is stored in a relational database, we recommend using your database internal backup tools. These usually offer better consistency guarantees. Should you decide to use the default Derby embeded database, be aware that performing backups of these files while the repository is in use offers no guarantee whatsoever as to the consistency of the contents of these files. You should always shutdown the repository prior to performing a backup.
- Application files
The enterprise application files should be taken in backup as well.
Email this
Print‑friendly