GraphDB-SE Installation

compared with
Current by Dimitar Manov
on Sep 18, 2014 19:02.

Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (72)

View Page History
h1. Upgrading

In most cases, upgrading GraphDB-SE can be achieved simply by replacing the GraphDB and bundled 3rd party jar files. The required version of the Sesame framework for the recent GraphDB OWLIM versions is given in the following table:

|| OWLIM/GraphDB version || Required Sesame version ||
| GraphDB-SE 5.4 | Sesame 2.7 |
| GraphDB-SE 5.3 | Sesame 2.6.7+ |
| GraphDB-SE 5.2 | Sesame 2.6.7+ |
| GraphDB-SE 6.0 | Sesame 2.7.8 + new index format (autoupgraded) - the same for Owlim 5.5|
| OWLIM-SE 5.5 | Sesame 2.7.8 + new index format (autoupgraded)|
| OWLIM-SE 5.4 | Sesame 2.7.8 |
| OWLIM-SE 5.3 | Sesame 2.6.7\+ |
| OWLIM-SE 5.2 | Sesame 2.6.7\+ |
| GraphDB-SE OWLIM-SE 5.1 | Sesame 2.6 |
| GraphDB-SE OWLIM-SE 5.0 | Sesame 2.6 |
| GraphDB-SE OWLIM-SE 4.3 | Sesame 2.6 |
| GraphDB-SE OWLIM-SE 4.2 | Sesame 2.5 |
| GraphDB-SE OWLIM-SE 4.1 | Sesame 2.4 |
| GraphDB-SE OWLIM-SE 4.0 | Sesame 2.4 |
| BigGraphDB BigOWLIM 3.5 | Sesame 2.3 |
| BigGraphDB BigOWLIM 3.4 | Sesame 2.3 |
| BigGraphDB BigOWLIM 3.3 | Sesame 2.3 |
| BigGraphDB BigOWLIM 3.2 | Sesame 2.3 |
| BigGraphDB BigOWLIM 3.1 | Sesame 2.2 |

Typically, Sometimes, the binary format of the storage files for different versions of BigGraphDB/GraphDB-SE BigOWLIM/OWLIM-SE/GraphDB-SE are not compatible. However, storage files created with version 3.1 and upwards will be automatically upgraded when using a later version of Owlim/GraphDB. However, this is a one-way process and no downgrade facility is provided.

{warning}
When upgrading to a later version of Owlim/GraphDB it is vitally important to make a back-up of your storage files before running the new software, because, otherwise, it will be impossible to revert to a previous version of GraphDB otherwise.
{warning}

h1. Easy install

GraphDB will is normally be built against the latest stable version of the [Aduna OpenRDF Sesame framework|http://www.openrdf.org/]. If using GraphDB with this version then the easiest way to deploy an a GraphDB 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 GraphDB distribution ZIP file. These Web applications have been modified as follows:

* *openrdf-sesame.war:* The Sesame server application. All GraphDB-SE 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 GraphDB-SE jar, XSLT configuration code and an a GraphDB-SE Turtle configuration file have been added, so that new GraphDB-SE instances can be created using the Workbench without the need to run the command line console application.

After deployment, an a GraphDB-SE instance 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-SE' from the drop-down and enter the repository ID and description. Then click 'next'.
* Fill in the fields as required (referring to the owlim-configurator spreadsheet as necessary) and click 'create' - if you have an a GraphDB-SE license file, its location should be specified in the license field. Note that paths must use '/' separators, even on Windows.
* 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).


A suitable application server must be installed. The examples in this guide assume [Apache Tomcat|http://tomcat.apache.org/] 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.
An [GraphDB-SE|http://www.ontotext.com/owlim/] A [GraphDB-SE|http://www.ontotext.com/products/ontotext-graphdb/graphdb-standard/] distribution is required. This is published as a zip file and includes the [Lucene|http://lucene.apache.org/] (core) full-text search utility jar file. The examples in this guide use version 5.4. 6.
If desired, the core version of Lucene can be replaced with the full Lucene jar that is available for download from the [Lucene website|http://lucene.apache.org/].
The [Aduna OpenRDF Sesame framework version 2.4|http://www.openrdf.org/] is required for the longer installation. The examples in this guide use version 2.7.

{note}Another application server can be used instead of Tomcat. However, the rest of this guide will describe describes the installation of GraphDB-SE 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.


Assuming that an instance of Tomcat is available, the installation proceeds as follows:
* Install and deploy Sesame;
* Install GraphDB-SE and deploy GraphDB-SE and other 3{^}rd^ party jar files (including Lucene-core);
* Add the GraphDB-SE repository template file to the Sesame console configuration;
* Use the Sesame console to create a new repository.;
* Set up a license file if you have one.


{note}
Alternatively, use the Tomcat manager interface at {{[http://localhost:8080/manager/html]}} to deploy the Web applications. If this approach is used, then ensure that a manager user account exists. The following lines should be added to: {{\[tomcat-directory\]/conf/tomcat-users.xml}} substituting your own password:
{code:xml}<tomcat-users>
<role rolename="manager"/>
{note}

* Restart Tomcat;
* Run the Sesame console once to create its configuration directory by executing {{\[SESAME\]/bin/console.sh}} (.bat) and then type {{quit .}} at the command prompt.;
* Locate the data directory here:
{noformat}$HOME/.aduna/openrdf-sesame-console* (linux/unix)
"$HOME/Library/Application Support/Aduna/OpenRDF Sesame console" (Mac OS X)
{noformat}
* Create the {{templates}} folder here and copy the GraphDB-SE repository template to it. This file is found here: {{\[GraphDBSE\]/templates/owlim-se.ttl}};
* Copy the GraphDB-SE jar file to the Sesame console and Sesame server, i.e. from {{\[GraphDBSE\]/lib}} to {{\[SESAME\]/lib}} and {{\[WEBAPPS\]/openrdf-sesame/WEB-INF/lib}};
* Copy the Lucene and other 3{^}rd^ party jars to the Sesame server, i.e, from {{\[GraphDBSE\]/ext}} to {{\[WEBAPPS\]/openrdf-sesame/WEB-INF/lib}};
* Restart Tomcat;
* Run the Sesame console {{\[SESAME\]/bin/console.sh (.bat)}};
* Connect to the local Sesame server with: {{connect}} {{[http://localhost:8080/openrdf-sesame]}} {{.}};
* Create a new repository: {{create owlim-se.}};
* Accept all the default values and then exit the console: {{quit.}}

* Create a new repository: {noformat}create owlim-se .{noformat}
* At this point values for a number of parameters are asked for, but all the defaults can be accepted by pressing {{<return>}} for each question. When finished, the message 'Repository created' should be displayed.
* Exit the console: {noformat}quit .{noformat}
* The status of the new repository can be checked using the Sesame workbench. Type the following URL in to a browser: {noformat}http://localhost:8080/openrdf-workbench{noformat}
* Alternatively, execute a test query against the Sesame Server's SPARQL endpoint:
* Run the Sesame console to create a new repository: {noformat}openrdf-sesame-2.7.2\bin\console.bat{noformat}
* Connect to the Sesame server: {noformat}connect http://localhost:8080/openrdf-sesame.{noformat}
* Create a new repository: {noformat}create owlim-se .{noformat}
* At this point values for a number of parameters are asked for, but all the defaults can be accepted pressing {{<return>}} for each question. When finished, the message 'Repository created' should be displayed, so exit the console: {noformat}quit .{noformat}
* The status of the new repository can be checked using the Sesame workbench. Type the following URL in to a browser: {noformat}http://localhost:8080/openrdf-workbench/{noformat}

h2. Sesame

The Sesame framework is published as a zip file that file,which is installed simply by unzipping it in to the target directory. This directory is called \[SESAME_INSTALL\] in this guide.
When running, Sesame stores configuration and repository data in the following directory:
| {{$HOME/.aduna/}} | On linux/unix operating systems. |
{noformat}export JAVA_OPTS='-Dinfo.aduna.platform.appdata.basedir=/other/dir/'
set JAVA_OPTS=-Dinfo.aduna.platform.appdata.basedir=\other\dir\
{noformat}Note that setting this environment variable must be done by the same user that runs the Tomcat server. This may not be the case when using 'sudo' to set up/start Tomcat, for instance when using port numbers below 1024, when it is necessary to run Tomcat with root privileges.
The Sesame 2 framework uses a special SYSTEM repository to store its configuration data. Do not store anything else in this repository.
The workbench Web application can be used for many administrative tasks, but it is still experimental. The easiest method to create new repositories is to use the Sesame Console script, which can be found in the bin directory: {{\[SESAME_INSTALL\]/bin/console.bat}} (.sh for linux/unix)
h2. Logging

The Sesame server and workbench use SLF4J for logging, although they each map to different underlying logging implementations. The Sesame server has bindings to [logback|http://logback.qos.ch/], whereas the Sesame workbench has bindings to the Java Runtime logging framework. By default, the Sesame server logs to:
{noformat}[ADUNA_DATA]/openrdf-sesame/logs/main.log{noformat}

h4. Can not create a GraphDB-SE repository using the Sesame console

Make sure that the repository template file \[GraphDBSE\]/templates/owlim-se.ttl GraphDBSE/templates/owlim-se.ttl has been copied to the 'templates' subdirectory of the Sesame console's data directory.

h4. Can not create an a GraphDB-SE repository, the Sesame console says unknown Sail type -- owlim:Sail

The Sesame console can not find the GraphDB-SE jar file. Make sure it was copied from \[GraphDBSE\]/lib GraphDBSE/lib to the Sesame installation folder here: \[SESAME\]/lib SESAME/lib

h4. A long error message/Java exception is given when trying to query a new repository instance.
h1. Installing GraphDB-SE with Jena

This section is for users and system administrators that are unfamiliar with the GraphDB-SE Jena adapter. The information contained in the following pages should be enough to get started with this software, i.e. to install and configure an a GraphDB-SE repository and access it via the Jena API or Jena compatible tools.
{note}
The Jena adapter allows GraphDB-SE to be used with local repositories, NOT those shared via the Sesame HTTP server. If you want to use GraphDB-SE remotely, consider using the Joseki server as described below.
h2. Required software

This guide covers installing and configuring the Jena adapter for [GraphDB-SE|http://www.ontotext.com/owlim/]. [GraphDB-SE|http://www.ontotext.com/products/ontotext-graphdb/graphdb-standard/]. Required software for this comprises:
* [Jena|https://repository.apache.org/content/repositories/releases/org/apache/jena/jena-core/] version 2.7 (tested with version 2.7.3)
* [ARQ|https://repository.apache.org/content/repositories/releases/org/apache/jena/jena-arq/] (tested with version 2.9.3)
h2. Description of the GraphDB-SE Jena adapter

The GraphDB-SE Jena adapter is essentially an implementation of the [Jena|http://jena.sourceforge.net/index.html] *DatasetGraph* _DatasetGraph_ interface that provides access to individual triples managed by an a GraphDB-SE repository through the Sesame API interfaces.
It is not a general purpose Sesame adapter and cannot be used to access any Sesame compatible repository, because it utilises an internal GraphDB-SE API to provide more efficient methods for processing RDF data and evaluating queries.
The adapter comes with its own implementation of a [Jena|http://jena.sourceforge.net/index.html] 'assembler' factory to make it easier to instantiate and use with those related parts of the Jena framework, although one can instantiate an adapter directly by providing an instance of a Sesame *SailRepository* (an GraphDB-SE *GraphDBRepository* implementation). Query evaluation is controlled by the ARQ engine, but specific parts of a Query (mostly batches of statement patterns) are evaluated natively through a modified *StageGenerator* plugged into the Jena runtime framework for efficiency. This also avoids unnecessary cross-api data transformations during query evaluation.

h2. Instantiate Jena adapter using a SailRepository

In this approach, an a GraphDB-SE repository is first created and wrapped in a Sesame *SailRespository*. Then a connection to it is used to instantiate the adapter class *SesameDataset*. The following example helps to clarify:
{code}import com.ontotext.trree.OwlimSchemaRepository;
import org.openrdf.repository.sail.SailRepository;
// finally, create the DatasetGraph instance
SesameDataset dataset = new SesameDataset(connection);
{code}From now on the {{SesameDataset}} object can be used through the Jena API as regular Dataset, e.g. to add some data into it one could do something like the following:
{code}Model model = ModelFactory.createModelForGraph(dataset.getDefaultGraph());
Resource r1 = model.createResource("http://example.org/book#1") ;
h2. Instantiate GraphDB-SE adapter using the provided Assembler

Another approach is to use the Jena assemblers infrastructure to instantiate an a GraphDB-SE Jena adapter. For this purpose the required configuration must be stored in some valid RDF serializsation format and its contents read into a Jena model. Then, the assembler can be invoked to get an instance of the Jena adapter. The following example specifies an adapter instance in N3 format.

{noformat}
otjena:datasetParam "./location" .
{noformat}
The {{ja:loadClass\*}} statements ensure that the GraphDB-SE Jena adapter factory class file(s) are initializsed and plugged into the Jena framework prior to be being invoked. Then the *\#dataset* description tells the Jena framework to expect instances of *otjena:SesameDataset* to be created by this factory. The following example uses such a description stored in the file *owlimbridge.n3* to get an instance of the Jena adapter:

{code:xml}
h2. Using GraphDB-SE with the Joseki server

In order to use a GraphDB-SE repository with the Joseki server one needs only to configure it as a dataset, so that the Jena assembler framework is able to instantiate it. An example Joseki configuration file that makes use of such a dataset description could looks like the following. First we describe a service that hosts the dataset:

{noformat}<#service1>
h1. Using GraphDB-SE with TopBraid Composer

All versions of GraphDB can be used with [TopBraid Composer/Live|http://www.topquadrant.com/products/TB_Suite.html], when set up using the Sesame HTTP server. When running TopBraid Composer, simply select File->New...->RDF/OWL Sesame2 RDF Repository Connection and enter the details (most importantly the server URL and repository ID).

However, TopBraid Composer can also use GraphDB-SE embedded, i.e. without needing to set up a server. To use TopBraid Composer and GraphDB-SE in this way, two components need to be installed:
The outline of the steps needed are as follows:

# Download the GraphDB bundle from Ontotext and copy it to the TopBraid Composer 'plugins' directory;
# Restart TopBraid Composer;
# Use the update manager to install the "GraphDB connector for TopBraid" from [http://www9.ontotext.com].

From now on GraphDB can be used with TBC in several ways as described below.

# Create an GraphDB database
# Create a GraphDB database:
## Select File->New->Other... then type GraphDB (to reduce the options) and then choose "RDF/OWL Local Owlim Database";
## Make any changes to the default configuration and press 'Create';
## Select in navigator view and open;
## It is now possible to use the SPARQL query view.

# Export to an GraphDB database
# Export to a GraphDB database:
## Open an ontology file;
## Select File->export->TopBraid Composer->Export/Merge/Convert RDF graphs;
## Choose "RDF/OWL Local Owlim Database";
## Complete the configuration.

h2. Memory requirements
{noformat}

Increase {{\-Xmx}} for larger databases.