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.
GraphDB is normally built against the latest version of the Aduna OpenRDF Sesame framework. If using GraphDB with this version then the easiest way to deploy an GraphDB server instance is to copy the re-packaged Sesame Web applications (.war files) in to the Tomcat webapps directory. They can be found in the sesame_owlim directory in the GraphDB distribution ZIP file. These Web applications have been modified as follows:
- openrdf-sesame.war: The Sesame server application. All GraphDB-Enterprise and 3rd party jar files have been added to this package, so that it can be used immediately after deployment.
- 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.
|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.|
After deployment, GraphDB-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 'GraphDB-Enterprise worker node' or 'GraphDB-Enterprise master node' from the drop-down list and enter the repository ID and description. Then click 'next'.
- For master nodes, there is nothing more to be specified, so just click 'create'. For worker nodes, fill in the fields as required (referring to the owlim-configurator spreadsheet as necessary) and click 'create'. You can specify a worker node license file at this step if you have one, but note that you must use forward slashes ('/') as file separators (even on Windows).
- A message is displayed, which gives details on the new repository and this should also appear in the repository list (click 'repositories' to see this).
|All configuration parameters that accept file/path names must use forward slashes ('/') even on Windows systems.|
|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).|
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 section below.
- Connect the workers to the master using the JMX interface - see Connect the worker nodes section below.
|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:|
See the FAQ for more details.
To set up additional master nodes, please refer to the "Longer install" section below.
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.
A suitable application server must be installed. The examples in this guide assume Apache Tomcat version 6.x is used. Importantly, the user must have sufficient privileges to write to the Tomcat webapps directory and to stop and start the Tomcat daemon.
A GraphDB-Enterprise distribution is required. This is published as a zip file. The examples in this guide use version 5.6.
The Aduna OpenRDF Sesame framework version 2.7 or higher is required for the longer installation. The examples in this guide use version 2.7.8.
Furthermore, a Java Development Kit (JDK) version 1.6 or later is necessary since this contains the jconsole management application.
|Another application server can be used instead of Tomcat. However, the rest of this guide describes the installation of GraphDB-Enterprise with this software.|
No part of this guide is intended to supersede the documentation published with the 3rd party software components and the reader is strongly advised to familiarise himself/herself with them.
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.
Installation of worker nodes proceeds exactly the same as when installing GraphDB-SE using the Sesame HTTP server, see the GraphDB-SE installation section. 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.
- 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.
- 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:
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.
If you want to setup several master nodes for the cluster, then before bringing each master online, configure its config file "cluster.properties" properly:
After that, continue with tomcat restart and Sesame console:
- Restart Tomcat:
- Run the Sesame console application:
- Connect to the tomcat instance just started
- Create a cluster master node:
- Exit the Sesame console:
At this point the master node is running, but the cluster it manages has no attached 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):
- 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:
- 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 can be monitored through the JMX client.
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.