Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

Introduction

This document provides detailed installation instructions for configuring and deploying VocBench version 2.0.

This guide is meant to remain as “static” as possible, along different configuration scenarios embracing data and vocabulary updates, changes in the various installation settings etc. For this reason, reference is made to an external wiki page on the google project site of VocBench:

https://code.google.com/p/agrovoc-cs-workbench/wiki/VB2_Installation

In the above wiki page, several configuration parameters have been defined, belonging to the different components which are part of VB2.0. The user may refer to a particular installation configuration presented there, as a series of ATTRIBUTE-VALUE pairs, where ATTRIBUTE is one of the configuration parameters required by the installation and VALUE represents the specific value which will be assigned for that particular configuration. This installation guide will use ATTRIBUTE names which are consistent with those present in the wiki.

The ATTRIBUTE will be explicitly mentioned by wrapping it between {} brackets.

E.g. {OWLIM.TOTAL_CACHE_MEMORY}

The installation package of Vocbench downloadable from its project site, which contains all or most of the components for installing VB2.0, will be referred along the guide as:

INST_PKG

When a file name for an installation component is referred in this guide without further specifying its full path, we are assuming it is in INST_PKG.

Pls contact the authors of this guide if you find any discrepancy in the use of any of the conventions explained above.

Requirements

Third Party Software

  1. Apache Tomcat web server (version 6.0 or higher)

    EXAMPLE: debian:apt-get update; apt-get install sun-java6-jdk apache2 tomcat6 libmysql-java


  2. MySQL database server (version  5.0 or higher)

    EXAMPLE:

    • debian:apt-get install mysql-server

    • Note Root password
    • Add extra users for VocBench if required

  3. OWLIM (Version {OWLIM.VERSION}).

Our Software

  • Semantic Turkey ServerVersion  {ST.Version}), but in any case use the packages found in INST_PKG: ST-Server.zip and SemanticTurkeyData.zip (see installation steps)
  • VocBench application war file  {VB.VERSION}
  • VocBench OSGi bundle for ST { ST.VB-BUNDLE.VERSION}

Data

  1. RDF Data File {DATA.VERSION}
  2. Administrator Database  {VB.DB.VERSION}

Installation Steps

Setting up the main Software Components

1.  OWLIM Setup    

2.  Semantic Turkey Server Setup

  • Unzip the package ST-Server.zip in a directory of your choice
  • In the same directory where the new ST-Server directory has been unzipped, unzip SemanticTurkeyData.zip (so that the extracted SemanticTurkeyData and the ST-Server folders are siblings under the same directory)Optional: you may change the content of the file install.cfg to have the SemanticTurkeyData directory into another position of your choice

In the directory ST-Server, there are batch files for Windows (.bat) and UNIX (.sh) to launch the server.

A further integration step would ask for VocBench OSGi bundle {ST.VB-BUNDLE.VERSION} to be copied inside the ST-Server directory under folder ST-Server\extensions\service. However, the OSGi bundle already comes packed inside the ST-Server, so perform this only if you get a specific update of the OSGi bundle.


3.  Import the Administrator Database SQL Dump File ({VB.DB.VERSION}) on MySQL Server

EXAMPLE: debian: mysql -u {your.db.user} -p < administrator20.sql

4.  VOCBENCH Setup  (don’t follow this if you have been redirected to this Full Installation guide from the QUICK installation guide, and come back instead to that guide)

  • Drop the {VB.VERSION} .war file in the Tomcat webapps folder
  • All the VocBench configuration parameters are setup using the property file “config.properties”. It is located under WEB-INF/classes folder of the uncompressed vocBench.war file
    • VB allows updating your configuration file at the time of first load after installation.
    • Here follows a series of properties which need to be setup only once. In general, these properties should have been already prepared by the developer before packaging the VB war file. In any case, we list them here for completeness:
      • CFG. VERSION: This value matches the value under the "version" field of the "ontology_info" table in the administration DB.          
        Scope: if we specify 2.0 in the property file, VB will show only those ontology in the vocbench which have 2.0 value.
        Default: This property should be 2.0 by default.
      • CFG. DISPLAYVERSION: Specifies which version you want to display in the VocBench UI.         
        Default: This property should be 2.0 by default.
      • CFG. MODE: specifies the deployment mode for the VOCBENCH           
        VALUES: can have these three values:
        • DEV: for Development
        • PRO: for production
        • SANDBOX: for sandbox
        • # DATABASE PROPERTIES
          • CFG.DB.CONNECTIONURL = jdbc:mysql://localhost:3306/<administrator_database_name>?requireSSL=false&amp;useUnicode=true&amp;characterEncoding=UTF-8
          • CFG.DB.USERNAME = your MySQL username for the account devoted to VB
          • CFG.DB.PASSWORD = your MySQL password for the account devoted to VB

Replace administrator_database_name with appropriate VocBench administrator database name, user & password values with the database username and password respectively. Also, the dbConnectionUrl may require further changes if you adopted a specific setup (you know how to handle them in case).

  • # MAIL PROPERTIES
    • CFG.MAIL.HOST =smtp.gmail.com (smtp adress or IP number)
    • CFG.MAIL.PORT =465 (smtp port)
    • CFG.MAIL.USER =agrovoc@gmail.com (user for login )
    • CFG.MAIL.PASSWORD =xxxxx (user password)
    • CFG.MAIL.FROM =aims@fao.org (from email address)
    • CFG.MAIL.FROM_ALIAS =VocBench Admin
    • CFG.MAIL.ADMIN =agrovoc@gmail.com (admin email address for approval)
    • CFG.MODELCLASS: set value as below to use Semantic Turkey:          
      org.fao.aoscs.model.semanticturkey.STManager
    • CFG.MANDATORY.DEFINITION.NAMESPACES = Add namespaces which requires mandatory definition's source and link (For multiple namespaces use semicolon ";" as a separator)
    • CFG.CODETYPE: set CODETYPE to “http://aims.fao.org/aos/agrovoc/AgrovocCode” if you want to set Agrovoc Code. Set it to empty if you are not installing VocBench for managing Agrovoc
    • CFG.CUSTOMDATATYPE: Add custom data types can be added via this parameter. To add multiple data types use semicolon ";" as a separator. For Agrovoc, add http://aims.fao.org/aos/agrovoc/AgrovocCode

Configuring a specific instance

1.    OWLIM REPOSITORY SETUP and DATA LOADING

and stop before the instruction starting with this text:
“Fill in the fields as required…”  
follow now the specific instructions here below for creating a repository

  • If you followed the above instructions, you should now be sitting in front of the sesame2 workbench web application, with the “New Repository” Form on the screen. There should be two text fields to be filled up, fill:
    • ID: {OWLIM.REPOSITORY_ID}
    • Title: whatever you like, the title is not important, it is just a comment field
    • After filling the above parameters and clicking on the next button, you will get to a second page with lot more parameters. Fill all of them with all the configuration parameters starting with the “OWLIM.” prefix, from the following configuration sections:
      • {OWLIM General}
      • {OWLIM Repository Configuration}
      • {Data Configuration}         

Also, other than all the “OWLIM.” prefixed properties, consider the {DATA.BASEURL} to be used in the “Base URL” field of the configuration.

In particular, be sure to check that all the parameters starting with {OWLIM. in the interested configurations have found a match in the entries (with a similar name) in the form, and leave untouched all those form fields which are not specified in the configurations.  
Confirm after all the fields have been filled up, by clicking the “create” button.

  • Now, the just-created repository should be already selected in the Sesame2 workbench. However, to be certain of that, click, from the menu on the left, on the “Repositories” section and then select the repository you just created.
  • Now it’s time to import the the SKOS Data file for the Concept Scheme you are using. To do so:
    • Click on the “Modify\Add” option on the left menu. You should see a form called “Add RDF”.
    • You may fill the Base URI field with the ({DATA.BASEURL}) value. However, if you import an NT file (which we recommend), there is no need to fill this field (the NT format already contains full URIs and no unprefixed local name). In any case, always uncheck the "use base URI as context identifier" and do not specify any value for "Context". Leave the other choices untouched.
    • Select with the radio button the option: “Select the file containing the RDF data you wish to upload” and then, in the “RDF Data File” field, choose the one specified in {DATA.VERSION} from your file system.
    • Then Click Upload

 2.   Add the new project to Semantic Turkey

This will be defined in a new version of the guide. If you have installed SemanticTurkeyData in the “Semantic Turkey Server Setup”, it will come with an already configured project for your first install.

Running the System

Running Semantic Turkey

  • Start Semantic Turkey by using the batch file in the ST-Server directory (server_run.bat for windows and server_run.sh for UNIX systems).

Running Vocbench

  1. Run Tomcat.
  2. Access VB from the browser at:

http://localhost:8080/<vocbench-deployment-name> (Change URL according to your configuration)

Example:

http://localhost:8080/vocbench-2.0

  1. VB has been preconfigured with administrator user. Use following credentials to connect as administrator. Administrators are the super users who can create new users and approve new users.

Administrator User Credentials:

Username: administrator

Password: 111111

In appendix A, there are specific instructions for performing some actions from behind-the-scenes, such as directly configuring a new project from the AdminDB of Vocbench, or creating the project through Semantic Turkey etc…

However, unless you experience some problem, you may follow the instructions in the next sections, which instruct the user on how to create and manage projects through the ST user interface


Project Management

After successful installation of VocBench, Semantic Turkey Server and OWLIM, a project has to be created, configured and populated with data.

The following sections instruct the user on how to create a new project

  1. Project Creation/Deletion
  2. SKOS Concept scheme Management
  3. Ontology Import
  4. Namespace Prefix Mapping Management
  5. Loading pre-existing data
  6. Enabling Indexing

1.   Project creation/deletion

Create new project    

  • Login with the administrator privilege (Only administrator are allowed to delete the project)
  • Once logged in, list of currently available project will be displayed.
  • On the top right corner, click [+] button to add the project.
  • Add window will be prompted to input following parameters:
    • Project name
      • Name of the new project (e.g. {ST.PROJECT.NAME})
    • Project description
      • Description of the project
    • Project type
      • Type of the project (OWL, SKOS, SKOS-XL)
      • Only SKOS-XL is available at the moment.
    • Base URI
    • Semantic Turkey Server URL
  • Click [Connect] button to test the connection to ST Server.
  • If failed, will prompt service failed message. Check if ST Server is running and connection URL is correct.
  • In case of successful connection, it will prompt list of triple Store
    • OntologyManagerFactorySesame2Impl
  • After triple store selection, it will prompt for available triple storage mode as follows
    • In memory/persistent
    • In memory/no persist
    • Native store/persistent
    • Remote access
  • Select remote access option and it will prompt to input following parameters:
    • repositoryId
      • ID of the sesame2 repository to be accessed  (e.g. {OWLIM.REPOSITORY_ID})
      • This should match the ID value used in repository (Repository ID value while creating new repository in OWLIM)
    • serverURL
    • Username
      • Identifier for the user connecting to the rdf repository
      • If not applicable, add “test” as this is mandatory field
    • Password
      • Password for the user connecting to the rdf repository
      • If not applicable, add “test” as this is mandatory field
    • Click on [?] icon to view each field information.
    • It is assumed that Repository Server is already running and new repository has been created.
    • Click [Add] button to create the project.
    • Newly created project will be added to the list.

 

 Delete project

  • Login with the administrator privilege (Only administrator are allowed to delete the project)
  • Once logged in, list of currently available project will be displayed.
  • Select the project to be deleted.
  • On the top right corner, click [-] button to delete the project.
  • Delete window with project name will be prompted.
  • Click [Delete] button to confirm deletion.
  • Delete project will be removed from the list.

 

2.   SKOS Concept Scheme management

  • After login, you will be directed to concept module.
  • If no concept scheme is selected by default, you will be prompted to go to Scheme module to select concept scheme.
  • Click on the [Schemes] link on the main menu bar, to go to Schemes module.
  • List of available concept schemes will be displayed.
  • If none of them is available, click [+] button on top right corner of list box to add new scheme.
  • Add scheme window will be prompted to add following parameters:
    • Scheme URI
    • Scheme label
    • Scheme language
  • After clicking [Add] button, newly added scheme will be displayed in the list.
  • To select the scheme, click on the check box.
  • To delete the scheme, click [-] button on the right end of each scheme.
  • Delete scheme window with scheme URI will be displayed.
  • Click [Delete] button to remove the concept scheme.
  • NOTE: Add/delete scheme is available only to administrator but selection of concept scheme is available to all users.

3.   Ontology Import

  • To import ontology, follow these link on the top menu bar
    • Administration > Ontology
  • Under Imports box, list of imported ontology will be displayed.
  • To import ontology, click [+] button on the top right corner
  • Four options are available
    • Add import from local file
      • This option will import ontology from the locally by providing following parameter
        • Base URI: base uri of the ontology (e.g. http://www.w3.org/2008/05/skos-xl#)
        • Local file : browse locally available ontology file (e.g. c:\skos-xl.rdf)
        • Mirror file: Name of the ontology file to be stored in server as mirror file (e.g. skos-xl.rdf)
    • Add import from ontology mirror
      • This option will import ontology from the mirror file available in the server by selecting from the list
  • To delete the imported ontology, click [-] button on the right end of each ontology.

4.   Namespace Prefix Mapping Management

  • To manage namespace, follow these link on the top menu bar
    • Administration > Ontology
  • Under namespace management box, list of available namespace with their prefix will be displayed.
  • To add new namespace, click [+] button on the top right corner
  • Provide namespace (http://aims.fao.org/aos/agrontology#) and prefix (agro) and click [Add] button.
  • To edit namespace, click [pen] button on the right end of the namespace in the list.
  • Change namespace prefix and click [Edit] button.
  • To delete namespace, click [-] button on the right end of the namespace in the list.
  • Delete namespace window will be prompted with namespace and prefix.
  • Click [Delete] button to delete the namespace.

5.   Loading pre-existing data

  • To load RDF data, click on the [Load data] link in the main menu bar.
  • Input following parameter
    • Base URI: base uri of the data to be imported. (e.g. http://aims.fao.org/aos/agrovoc/)
    • RDF file: browser data file to be imported. (e.g. agrovoc_wb_20130507_VB.nt)
  • Click [Import button] to import data.
  • This process may take some time depending on the size of the data.

6.   Enabling indexing

  • To enable indexing, click on [Advanced search] link below top menu bar at the top right end.
  • Click on the [index] button at the right end.
  • It will prompt to confirm if you want to index. Click the [Ok] button to enable indexing.
  • This process may take some time.
  • This action is only available to administrator users.

 

Creating a new User

We suppose here that you are both the user and administrator of vocbench (see section 4 on VOCBENCH setup).

To add a new user in VocBench follow these steps:

  • Go to http://localhost:8080/vocbench-2.0/index.html and click on "Create an account" under the login form on the right of the page
  • Input all the required information. It is better, even if it is not mandatory, to specify the "Languages you wish to manage" and the "Ontology you wish to manage"
  • At this point the account is not yet allowed to log on.
    • As a user, you can wait for the confirmation email that a request has been sent to the administrator
    • As administrator, you can wait for the email and follow its instructions

If you do not receive any email (maybe a misplaced configuration) you need to manually enable the account by modifying the admin DB (see FAQ 1)

 

There is a list of Frequently Asked Questions (FAQs) addressing specific issues related to installation

Appendix A: Behind the Scenes Configuration and Management

Configuring the Administration DB for a new project        

The following steps can be skipped if the new project is created through the VocBench interface.

VocBench stores all the ontologies information in the “Administrator database” under “ontology_info” table. The structure of this table contains various fields. Please ignore the fields: (db_url, db_driver, db_name_ db_password) as the RDF data is no more stored in a database. These fields have been maintained for compatibility with the previous 1.3 version of VB (thus enabling use of the same admin DB with two different versions of VB).

ontology_id: (Auto increment)

ontology_name: <ontology-name> (use {ST.PROJECT.NAME})

ontology_description: <description-of-ontology> (not important)

db_url: null

db_driver: <ST-Server URL>    (e.g. http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer)

db_name: (use {ST.PROJECT.NAME})

db_username: null

db_password: null

ontology_show: 0 for hide and 1 for show  (use 1)

version: <version-number>          (this should be 2.0 for VB2.0 data)

You may check through some explorer tool if the data is already configured in the Administrator Database that you have downloaded. However, these instructions allow you to define a new entry, should you have the system already installed, but in need of setting up a new project/configuration.

Here follows an example for immediately adding an entry to the admin db for a new project.

To connect to different ST server instances, set the value of <db_driver> with different ST server URL.

debian: mysql –u root –p

mysql> Show databases

mysql> Use < administrator database>

mysql> SELECT * FROM ontology_info

 

'1', 'AGROVOC_SKOS_VB_2013-02-05', 'Full Agrovoc', '', 'http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer', 'AGROVOC_SKOS_VB_2013-02-05', '', '', '1', '2.0'

'2', 'AGROVOC-PRODUCTS-AGRONTOLOGY', 'Agrovoc small cut with top concept Products', '', '', '', '', '', '0', '2.0'

 

You will see that ontology with project name 'AGROVOC_SKOS_VB_2013-02-05’ is already configured for VB 2.0. If you want to add new ontology, follow query below.

mysql> INSERT INTO ontology_info

(ontology_name, ontology_description, db_url, db_driver, db_name, db_username, db_password, ontology_show,version) values

(“{ST.PROJECT.NAME}”, "AGROVOC Multilingual Thesaurus", null, “http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer”, “{ST.PROJECT.NAME}”, null,

null, "1","2.0");

Managing a project through Semantic Turkey services   

The following actions (Import ontology, Namespace management) can be skipped as can done via VocBench interface.

  • Then from a web browser paste the following URLs and wait for their relative responses:

http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer?service=projects&request=openProject&name={ST.PROJECT.NAME}

  • This action may take a while, as Semantic Turkey is importing the definition of OWL, SKOS and SKOS-XL dictionaries. This is done only the first time the project is being created. You should see an XML reply on the browser (and in the STServer console if proper logging is activated) once the request is satisfied.
  • The first time that you run Semantic Turkey on a given project, you have to import the ontology: agrontology.owl (you need an internet connection!), containing all the domain properties used in AGROVOC and other FAO concept schemes. This is the service call:

http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer?service=metadata&request=addFromWebToMirror&baseuri=http%3A%2F%2Faims.fao.org%2Faos%2Fagrontology%23&mirrorFile=agrontology.owl

  • This action takes a while, as Semantic Turkey will download the agrontology and, recursively, other ontologies imported by it, such as VOAF and Dublin core. You can check news on the console, if proper logging is activated.
  • Check if the import is successful by running query below:

http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer?service=metadata&request=getImports

  • Add namespace prefix for imported agrontology vocabulary.

http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer?service=metadata&request=setNSPrefixMapping&prefix=agrontology&namespace=http://aims.fao.org/aos/agrontology%23

  • Check added namespace mapping in the list by running query below.

http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer?service=metadata&request=getNSPrefixMappings

Appendix B: OWLIM specific notes

How to use a custom ruleset

OWLIM allows for loading custom rulesets (used for inferencing) instead of the precompiled ones bundled with the OWLIM distribution. In particular, their standard OWL rulesets seem to have some bugs in the axiomatic triples (probably originating from wrong definitions in the OWL RL specifications), thus it may be mandatory to load custom versions of these rulesets. Here follow instructions for loading custom rulesets.

Custom rulesets may be easily loaded by specifying the full path to their file location as a value for the OWLIM configuration parameter: “ruleset” (instead of the code name of the standard ones).

However, while this is pretty straightforward when specifying an OWLIM configuration programmatically, doing this through the Sesame2 workbench is not trivial, as the workbench only allows for pre-defined values (associated to the standard preloaded ruleset).

Here follows the instructions for changing ruleset in Sesame2 workbench

The instructions have been compiled by following the example reported in this post on the OWLIM forum:

http://answers.ontotext.com/questions/996/archive-setting-ruleset-owlim-repository-using-sesame-workbench

  • Create a new repository, but do not initialize it! (don't access it, or at least don't put data into it). When selecting the parameters for the repository, select the “Empty” ruleset.
  • Now, select the “SYSTEM” repository, and perform the following SPARQL query:

PREFIX sys:  <http://www.openrdf.org/config/repository#>    
PREFIX sail: <http://www.openrdf.org/config/repository/sail#>
PREFIX onto: <http://www.ontotext.com/trree/owlim#>
SELECT ?g ?sail ?param ?value
WHERE {
    GRAPH ?g { ?rep sys:repositoryID ?id . }
    GRAPH ?g { ?rep sys:repositoryImpl ?impl . }
    GRAPH ?g { ?impl sys:repositoryType ?type . }
    GRAPH ?g { ?impl sail:sailImpl ?sail . }
    GRAPH ?g { ?sail ?param ?value . }
    FILTER( ?id = "{OWLIM.REPOSITORY_ID}" ) .
    FILTER( ?param = onto:ruleset ) .
}


to check that the parameter is, as expected, the “empty” value that has been selected when creating the repository. Note the use of the OWLIM.REPOSITORY_ID, which you must obviously replace with your OWLIM repository ID.

  • Now, perform the following SPARQL update:

PREFIX sys:  <http://www.openrdf.org/config/repository#>
PREFIX sail: <http://www.openrdf.org/config/repository/sail#>
PREFIX onto: <http://www.ontotext.com/trree/owlim#>
DELETE { GRAPH ?g {?sail ?param ?old_value } }
INSERT { GRAPH ?g {?sail ?param ?new_value } }
WHERE {
   GRAPH ?g { ?rep sys:repositoryID ?id . }
   GRAPH ?g { ?rep sys:repositoryImpl ?impl . }
   GRAPH ?g { ?impl sys:repositoryType ?type . }
   GRAPH ?g { ?impl sail:sailImpl ?sail . }
   GRAPH ?g { ?sail ?param ?old_value . }
   FILTER( ?id = "{OWLIM.REPOSITORY_ID}" ) .
   FILTER( ?param = onto:ruleset ) .
   BIND( "<directorypathtoyourcustompiefile>/builtin_owl2-rl-fixed.pie" AS ?new_value ) .
}

 

by changing the parameters of the last and the third to last rows in the following way:

  • Again, replace the value associated to ?id with the id of the repo you want to modify
  • replace the value on the BIND, with the absolute path of a custom rule set (it is possible to omit the ending .pie extension, it will be attached by default)
  • You may re-perfom the initial query to check that the substitution for the variable ?value is now the path to the custom ruleset that you defined.
  • Close and restart tomcat, as OWLIM needs to compile the new ruleset
  • Now the repository is ready for receiving data, which will be analysed and expanded into new triples through inference, by exploiting the new ruleset.
  • No labels