GraphDB-Enterprise Installation

The information contained in this section should be sufficient to get started with GraphDB-Enterprise, i.e. to install and configure the software on both master and worker nodes.

{toc}

* *openrdf-workbench.war:* The GraphDB-Enterprise jar, XSLT configuration code and the GraphDB-SE Turtle configuration files have been added, so that new GraphDB-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 to 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 GraphDB-SE, it is essential that the GraphDB-Enterprise distribution is used for all nodes in a cluster, i.e. both masters and workers.
{note}

{info}
All configuration parameters that accept file/path names must use forward slashes ('/') even on Windows systems.
{info}

The last steps to get the cluster connected and running are as follows:
* Set up the master node's Tomcat instance to expose its JMX interface - see [Install master node|GraphDB-Enterprise Installation#Install master node] section below.
* Connect the workers to the master using the JMX interface - see [Connect the worker nodes|GraphDB-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 GraphDB 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_with_forward_slashes>}}
See the [FAQ|GraphDB FAQ#How do I set up license files for GraphDB-SE and GraphDB-Enterprise] for more details.
{note}

(i) To set up additional master nodes, please refer to the "Longer install" section below.

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 GraphDB-Enterprise files need to be installed alongside Sesame in a step-by-step process as follows.

h2. Preparation

Furthermore, a [Java Development Kit (JDK)|http://www.oracle.com/technetwork/java/javase/downloads/index.html] version 1.6 or later is necessary since this contains the {{jconsole}} management application.

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


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 GraphDB-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 proceeds exactly the same as when installing GraphDB-SE using the Sesame HTTP server, see the [GraphDB-SE installation section|GraphDB-SE Installation]. However, there are several important differences:

# The GraphDB-Enterprise jar (owlim-enterprise.<version>.jar) file must be used instead of an GraphDB-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 [GraphDB-SE Advanced Features|GraphDB-SE Experimental Features].
# A worker configuration template file {{worker.ttl}} is included in the GraphDB-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 a GraphDB-SE instance, but use the GraphDB-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. First, choose a JMX port number, this example uses port 8089. Then, set the *CATALINA_OPTS* environment variable, 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}
Alternatively, use the {{JAVA_OPTS}} environment variable, or if using Windows, right click on the Tomcat monitor icon in the system tray, select the Java tab and add the above options to the 'Java Options' field. If starting and stopping Tomcat using the {{service}} command under Linux, then it might be easier to edit the script {{/etc/init.d/tomcat6}} and set CATALINA_OPTS there.

h3. Setting additional master nodes

If you want to setup several master nodes for the cluster, then before bringing each master online, configure its config file "cluster.properties" properly:
* location
<master-repository>/cluster.properties

* format
{code}
version=2.0
node-id=master3

#own workers
node.1.url=http\://node1\:8080/openrdf-sesame/repositories/worker
node.2.url=http\://node2\:8080/openrdf-sesame/repositories/worker

#peers
peer.1.id=master1
peer.1.url=http\://server1\:21200/openrdf-sesame/repositories/master
peer.2.id=master2
peer.2.url=http\://server1\:20800/openrdf-sesame/repositories/master

#replication
min-time-to-consider-full-replication-s=600
net-speed-bits-per-sec=104857600

#misc
remote-master=false
slow-op-threshold-ms=0
system-transaction-password=
timeout=-1
update-timeout=-1

{code}

After that, continue with tomcat restart and Sesame console:

* Restart Tomcat: {code}service tomcat6 restart{code}
* Run the Sesame console application: {code}openrdf-sesame-2.7.8\bin\console.bat (Windows)
openrdf-sesame-2.7.8/bin/console.sh (Unix/Linux){code}
* Connect to the tomcat instance just started {code}connect http://localhost:8080/openrdf-sesame .{code}
* Create a cluster master node: {code}create master.{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 needs to be expanded by double-clicking on it. The newly added worker node is 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 found 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-write repository, notifications and [statistics|GraphDB-SE Configuration] can be monitored through the JMX client.


h2. Put the cluster in to read-write mode

In 5.6 all masters are always read-write, there is no additional step to put the master in RW mode, as in previous versions.