OWLIM-Enterprise Installation

This document is for users and system administrators that are unfamiliar with the OWLIM-Enterprise software. The information contained in the following pages should be enough to get started with OWLIM-Enterprise, i.e. to install and configure the software on both master and worker nodes.

{toc}

h1. Description

A cluster is made up of two basic node types: masters and workers. A master node is responsible for:
* ensuring that all worker nodes are synchronised
* propagating updates (insert and delete tasks) across all workers and checking updates for inconsistencies
* load balancing read requests (query execution tasks) between all available worker nodes
* providing a uniform entry point for client software, where the client interacts with the cluster as though it is just a normal [Sesame openRDF|http://www.openrdf.org/] repository
* providing a JMX management interface for monitoring and administrating the cluster
* automatic cluster re-configuration in the event of failure of one or more worker nodes
* user-directed dynamic configuration of the cluster to add/remove ẃorker nodes

Worker nodes are based on OWLIM-SE and are set up using the Sesame HTTP server (a Web application running inside a servlet container, e.g. Apache Tomcat). Master nodes do not store or manage any RDF data themselves (although it is possible to run a master and a worker instance on the same physical machine). From an external point of view, a master behaves exactly like any other Sesame repository that is exposed via the Sesame HTTP server, but internally utilises worker nodes (also exposed via the Sesame HTTP server) to store and manage RDF data. In this way, parallel query execution performance can be increased by having worker nodes answer queries in parallel.
OWLIN-Enterprise therefore has two advantages over a stand-alone OWLIM-SE instance:
* Improved parallel query execution performance.
* Resilience to hardware failures of individual nodes in the cluster.
Furthermore, each cluster can contain more than one master node. In this case, every master monitors the health of all the workers and can distribute query execution tasks between them, effectively allowing a cluster to have multiple entry points for queries. However, only one master at any given time can be responsible for propagating updates across the workers and this node is said to be in 'normal' (also called 'read/write') mode. All other master nodes are in the 'hot-standby' (also called 'read-only') mode. Switching the modes of master nodes can be achieved using the JMX management interface.

The rest of this guide gives detailed step by step instructions for installing and configuring an OWLIM-Enterprise cluster that contains both master and worker nodes.

h1. Easy install

OWLIM will normally be built against the latest version of the [Aduna OpenRDF Sesame framework|http://www.openrdf.org/]. If using OWLIM with this version then the easiest way to deploy an OWLIM server instance is to copy the re-packaged Sesame Web applications (.war files) in to the Tomcat {{webapps}} directory. These can be found in the {{sesame_owlim}} directory in the OWLIM distribution ZIP file. These Web applications have been modified as follows:

* *openrdf-sesame.war:* The Sesame server application. All OWLIM-Enterprise and 3{^}rd^ party jar files have been added to this package, so that it can be used immediately after deployment.
* *openrdf-workbench.war:* The OWLIM-Enterprise jar, XSLT configuration code and an OWLIM-SE Turtle configuration files have been added, so that new OWLIM-Enterprise instances can be created using the Workbench without the need to run the command line console application.

The repackaged openrdf-sesame.war Web application must be deployed to all cluster nodes. The openrdf-workbench.war Web application need only be deployed on a single machine and this does not have to be a machine taking part in the cluster. However, for simplicity, it is more straightforward to deploy the workbench to all nodes simultaneously with the Sesame server.

{note}
Even though the worker nodes are based on OWLIM-SE, it is essential that the OWLIM-Enterprise distribution is used for all nodes in a cluster, i.e. both masters and workers.
{note}

After deployment, OWLIM-Enterprise master and worker nodes can be created using the workbench application as follows:
* Start a browser and go to the Workbench Web application using a URL of this form: [http://localhost:8080/openrdf-workbench/] \- substituting {{localhost}} and the {{8080}} port number as appropriate.
* Click 'change server' if necessary to select a Sesame server instance if it is running on a different machine. The server URL will be of this form: [http://localhost:8080/openrdf-sesame]
* After selecting a server, click 'New repository'
* Select 'OWLIM-Enterprise worker node' or 'OWLIM-Enterprise master node' from the drop-down and enter the repository ID and description. Then click 'next'.
* For master nodes, there is nothing more to specified, so just click 'create'. For worker nodes, fill in the fields as required (referring to the owlim-configurator spreadsheet) and click 'create'. You can specify a worker node license file at this step if you have one.
* A message should be displayed that gives details of the new repository and this should also appear in the repository list (click 'repositories' to see this).

{note}
All worker nodes that take part in the same cluster (connect to the same master), must be configured identically (apart from the repository name and label).
{note}

The last steps to get the cluster connected and running are:
* Set up the master node's Tomcat instance to expose its JMX interface - see [Install master node|OWLIM-Enterprise Installation#Install master node] section below.
* Connect the workers to the master using the JMX interface - see [Connect the worker nodes|OWLIM-Enterprise Installation#Connect the worker nodes] section below.

{note}
License files are not required for master nodes. License files for worker nodes can be set using the Sesame console or Workbench when creating repositories. These values can be overridden by using a command line parameter for the Java virtual machine (JVM) that hosts the OWLIM instances. The easiest way to pass configuration parameters when using Tomcat is to use the {{CATALINA_OPTS}} environment variable. The worker license file can be set using:
{{CATALINA_OPTS=-Dowlim-license=<path_to_worker_license_file>}}
See the [FAQ|OWLIM FAQ#How do I set up license files for OWLIM-SE and OWLIM-Enterprise] for more details.
{note}

h1. Longer install

This longer install process should be used when a different or modified version of Sesame is being used. In this case, all the OWLIM-Enterprise files need to be installed alongside Sesame in a step-by-step process as follows.

h2. Preparation

{note}Another application server can be used instead of Tomcat. However, the rest of this guide will describe the installation of OWLIM-Enterprise with this software.
{note}No part of this guide is intended to supersede the documentation published with these 3{^}rd^ party software components and the reader is strongly advised to familiarise himself/herself with these.


h2. Installation steps

Assuming that an instance of Tomcat is available on all cluster nodes, the installation proceeds as follows:
* Install worker nodes
* Install master nodes
* Connect worker nodes to master nodes
* Bring the master in to read-write mode

One thing to remember is that although workers behave like a standard OWLIM-SE instance, worker nodes need to expose a cluster management end-point (when necessary) using a port number that is given by the Tomcat port number plus 10, i.e. usually 8080 + 10 = 8090. You must make sure that no other software is listening on this port number.

h2. Install worker nodes

Installation of worker nodes precedes exactly the same as when installing OWLIM-SE using the Sesame HTTP server, see the [OWLIM-SE installation section|OWLIM-SE Installation]. However, there are several important differences:

# The OWLIM-Enterprise jar (owlim-enterprise.<version>.jar) file must be used instead of an OWLIM-SE jar file.
# If notifications are to be set up for the cluster, care must be taken to configure JMX for the worker nodes, see the remote notifications section of [OWLIM-SE Advanced Features|OWLIM-SE Advanced Features].
# A worker configuration template file {{worker.ttl}} is included with the OWLIM-Enterprise distribution - this can be used in place of the {{owlim-se.ttl}} file.

h2. Install master node

* Install the master node as though it is an OWLIM-SE instance, but use the OWLIM-Enterprise jar file and a different configuration template. A suitable template called {{master.ttl}} can be found in the {{templates}} folder of the distribution ZIP file.
* Configure the Tomcat instance to expose its JMX interface, which can be done in a variety of ways. Firstly, a JMX port number must be chosen, this example uses port 8089. Then the *CATALINA_OPTS* environment variable can be set so that the Tomcat server exposes the JMX interface on this port number:
{code}set CATALINA_OPTS="-Dcom.sun.management.jmxremote.port=8089
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false"{code}

* Exit the Sesame console: {code}quit .{code}

At this point the master node is running, but the cluster it manages has no attached worker nodes.

h2. Connect the worker nodes

* Ensure that the replication cluster is loaded by the HTTP server by starting the openrdf workbench and selecting it. To do this open a browser and connect to the workbench using this url (or similar): {code}http://localhost:8080/openrdf-workbench/{code}
* Use the workbench to select the correct HTTP server where the replication cluster instance is running. Then choose the replication cluster repository instance. This will have the ID as entered when the repository was created.
* It will likely be necessary to 'force' the repository to load and initialise by clicking on the *query* button. This will cause an exception to be displayed containing the text 'No available worker nodes'.
* Start a JMX client, e.g. {{jconsole}} from the Java Software Development Kit.
* Connect to the Tomcat process using the port number selected above. When using a non-standard port number (as in this case), connect as a remote process using localhost:<port_number>. In this example enter the following: {code}localhost:8089{code}
* After connecting, select the *MBeans* tab and open the *ReplicationCluster* bean (if this is not visible, try to force the instance in to memory as described above).
* Add worker nodes using the *addClusterNode* operation. Two or more parameters are required, the first is the URL of the HTTP endpoint, e.g. [http://localhost:8080/openrdf-sesame/repositories/worker1], and the second is the port number used for replication. At the moment, this is hard-coded to be the servlet container (Tomcat) port number plus 10, so usually this will be *8090*. Any other parameters can be ignored at this stage.
* To ensure that the worker node has been added correctly, check the attribute *NodeStatus*. This is an array and will need to be expanded by double-clicking on it. The newly added worker node will be shown here with its full URL. If it has been added successfully, it will have the status *\[ON\]*. If however, it has the status *\[OFF\]* then the node has not been added properly. A common mistake is to enter the Sesame workbench URL (containing '...openrdf-workbench...') instead of the repository endpoint URL (containing '...openrdf-sesame...'). The proper URL to use can be seen in the list of repositories shown in the workbench by clicking on the the 'Repositories' link in the left-hand menu (assuming that the workbench is already using the correct Sesame server).

As soon as one or more workers have been attached. the cluster can now be used as a read-only repository, notifications and [statistics|OWLIM-SE Configuration] can be monitored through the JMX client.

h2. Put the cluster in to read-write mode

When a master is brought online, it will be in read-only mode, otherwise known as 'hot-standby'. To put the master in to read-write mode, attach to its JMX interface (using jconsole) and set the *ConfiguredWritable* attribute to *true*. If there is no problem, then the *IsWritable* attribute should now also change to *true*. At this point, the cluster can be used like any other OWLIM-SE repository shared over HTTP.