Getting started with the EXPERImonitor

There is a binary and source release of the EXPERImonitor. The source release contains all the source code for the EXPERImonitor service and clients. The binary release just contains a pre-built EXPERImonitor service WAR file. If you are a client developer then the source release is required. If you just need to deploy the EXPERImonitor service then only the binary release is needed.

Acquiring the required 3rd party libraries

In addition to the EXPERImonitor distribution, you will also need to acquire some third party libraries that we cannot redistribute due to their licenses.

Library	Description
owlim-lite-5.4.jar	Required to build the EXPERImonitor and must be added to the binary release
openrdf-sesame.war	Required to be deployed in either Tomcat or Glassfish before the EXPERImonitor is installed
openrdf-workbench.war	Optionally deployed in either Tomcat or Glassfish to support browsing of raw RDF data generated by the EXPERImonitor

To obtain these file, please register with Ontotext by visiting http://www.ontotext.com/owlim/owlim-lite-registration. After filling out the registration form, a download link will be sent to your email address. The download consists of a single zip file, typically named something like “owlim-lite-5.4.xxxx.zip”. Having received the email, follow these steps:

1. Download the owlim-lite zip file
2. Extract the files lib/owlim-lite-5.4.jar, sesame_owlim/openrdf-sesame.war and sesame_owlim/openrdf-workbench.war from the Ontotext distribution
3. Copy the files into the thirdPartyLibs folder of the EXPERImonitor distribution

EXPERImonitor dependencies and licenses

The EXPERImonitor software requires various third-party libraries to compile and/or execute. These libraries and their associated licences are detailed in the following file:

<EXPERImonitor distribution root> / IPR.txt

Source release

The source release can be built manually or can be automatically copied into a virtual machine, built and the service deployed using vagrant.

Deploying the EXPERImonitor service using Vagrant

The quickest method of building and deploying the EXPERImonitor is to use the Vagrant deployment method: this creates a virtual machine on your host and automatically installs all the pre-requisites (such as PostgreSQL, Tomcat, RabbitMQ) and builds and deploys the EXPERImonitor for you. Once you have acquired the EXPERImonitor software package and its library dependencies, you will need to:

1. Install Oracle VM VirtualBox (visit https://www.virtualbox.org/ for more details)

2. Install Vagrant (visit http://www.vagrantup.com/ for more details)

3. Make a copy the appropriate Vagrant deployment file in the EXPERImonitor root directory:

   • To deploy into Tomcat: Copy Vagrantfile.tomcat -> Vagrantfile
   • to deploy into Glassfish: Copy Vagrantfile.glassfish -> Vagrantfile

Starting the vagrant virtual machine

This is done by simply typing “vagrant up” in the <EXPERImonitor API root> folder which will execute the instructions found in the “Vagrantfile” you have just selected. The shell script embedded in the vagrantfile is also a useful reference for deploying the system in Linux.

Once the build is completed, the EXPERImonitor and a RabbitMQ server are hosted in a virtual machine with the necessary ports mapped through to the host machine. The port mapping can be changed via environment variables in the host machine:

ECC_IP: the IP address for the EXPERImonitor VM to use (default 10.0.0.10) ECC_PORT: the port to map the EXPERImonitor to on the host machine (default 8090) RABBIT_IP: the IP address to use for RabbitMQ (default 10.0.0.10) RABBIT_PORT: the port to map RabbitMQ to on the host machine (default 5682) RABBIT_MGT_PORT: the port to map RabbitMQ management interface to on the host machine (default 55682)

The sample clients distributed with the EXPERImonitor generally attempt to connect to a RabbitMQ server running on localhost with the default 5672 port. To make these clients work with the EXPERImonitor and RabbitMQ in the vagrant VM you must map the guest VM’s RabbitMQ port through to port 5672 in the host machine. This is achieved by setting the variable “RABBIT_PORT” to 5672 on the host machine.

Building the EXPERImonitor manually

Pre-requisites

The following tools are required to build the EXPERImonitor service and libraries:

• Java JDK 1.7 (Oracle JDK for Windows and OpenJDK for Ubuntu have both been tested)
• Maven 3.0
• OWLIM Lite 5.4 (see above)

Install these tools according to their instructions for your platform.

Building

You are now ready to build the EXPERImonitor. To do this get a command line in the root of the EXPERImonitor distribution and type:

cd thirdPartyLibs
installLibraries.bat (Windows) or ./installLibraries.sh (Limux)
cd ..
mvn clean install

All modules in the EXPERImonitor should be reported as successfully built. You should find the EXPERImonitor web dashboard WAR file created in the following location:

eccService/target/EccService-2.2.war

To deploy the EXPERImonitor service use mvn spring:boot or follow the instructions for the “Binary release” below.

spring:boot

A fast way of deploying the EXPERImonitor often prefered by developers is to use spring:boot.

1. Change into eccService folder
2. Run the mvn spring:boot command.

This results in the EXPERImonitor service deployed in a built-in Tomcat container on http://localhost:8083/ECC (port and context configurable via server.port and server.context-path properties in eccService/src/main/resources/application.properties file).

For this deployment method you may wish to change the logging configuration such that the EXPERImonitor log file is placed somewhere useful. To do this, edit the LOG_DIR variable definition in the eccService/src/main/resources/logback.xml file.

Binary release and web service deployment

Pre-requisites

The following tools are required to deploy and run the EXPERImonitor service:

• Java JDK 1.7 (Oracle JDK for Windows and OpenJDK for Ubuntu have both been tested)
• RabbitMQ server 2.8.6 (or better)
• PostgreSQL 9.1
• Apache Tomcat 7.x or Oracle Glassfish 3.1.2.2
• Supporting third party libraries (see above)

RabbitMQ

The RabbitMQ server can be deployed on the same machine as the EXPERImonitor service or on a separate host.

Windows installation

You can download the RabbitMQ server from: http://www.rabbitmq.com/download.html

1. Install RabbitMQ v2.8.6 or later for Windows (please follow instructions from the RabbitMQ website, including the dependency on Erlang)
2. Open an adminstrator level Command window in your RabbitMQ server ‘sbin’ folder
3. Start the RabbitMQ server, by typing: rabbitmq-service start

Ubuntu Linux installation

Execute the following commands:

$ sudo apt-get install rabbitmq-server
$ sudo /usr/lib/rabbitmq/lib/rabbitmq_server-2.7.1/sbin/rabbitmq-plugins enable rabbitmq_management
$ sudo service rabbitmq-server restart

You should have a RabbitMQ server service running using the default RabbitMQ port: http://localhost:5672. If you also installed the web-based management system, you should be able to view the status of your RabbitMQ server by navigating to http://localhost:55672 The EXPERImonitor is set up by default to use this local address.

PostgreSQL

The PostgreSQL server can be deployed on the same machine as the EXPERImonitor service or on a separate host. We recommend it is deployed on the same host.

The default login details used by the EXPERImonitor to connect to the database are:

• Username: postgres
• Password: password

Please see the PostgreSQL documentation to understand how to set the username and password for the database. The username and password can be configured in the EXPERImonitor (see below).

The database schema is defined in the edm/resources/edm-metrics-postgres.sql file of the EXPERImonitor distribution.

Windows installation

Download PostgreSQL from http://www.postgresql.org/download/ Install PostgreSQL and the pgAdmin tool using the graphical installer.

1. Create a database called edm-metrics with UTF-8 encoding
2. Execute the SQL script found in the EXPERImonitor package:

psql -d edm-metrics -U<username> -f edm/resources/edm-metrics-postgres.sql

Above, the term <username> refers to your chosen username.

Ubuntu Linux installation

Install PostgreSQL and create the database by executing:

$ sudo apt-get install postgresql-9.1
$ sudo -u postgres createdb -T template0 edm-metrics --encoding=UTF8 --locale=en_US.utf8
$ sudo -u postgres psql -d edm-metrics -f edm/resources/edm-metrics-postgres.sql

Apache Tomcat 7.x

Apache Tomcat or Glassfish can be used to host the EXPERImonitor service.

Windows installation

Download Tomcat from http://tomcat.apache.org/download-70.cgi and run the installer.

TODO: memory to 1GB?

After installing the Tomcat server, you should have a Tomcat service running – this can be verified by navigating to the management web page usually found at http://localhost:8080/

Deploy and run the EXPERImonitor service by copying the two WAR files from the thirdPartyLibs folder and eccService/target/EccService-2.2.war to Tomcat’s webapps directory (Tomcat should automatically unpack and deploy them for you immediately).

Copy the owlim-lite-5.4.jar from thirdPartyLibs to the uppacked EXPERImonitor service TODO where? Then restart the Tomcat service.

You should see the EXPERImonitor dashboard running on: http://localhost:8080/EccService-2.2

Ubuntu Linux installation

Install Tomcat:

$ sudo apt-get install tomcat7
$ sudo apt-get install tomcat7-admin

Enable the tomcat manager webapp by editing the /etc/tomcat7/tomcat-users.xml file.

Increase the memory allocation for Tomcat to at least 1GB by editing /etc/default/tomcat7 to e.g. include the line:

JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m -XX:+UseConcMarkSweepGC"

Add the aduna folder to the tomcat installation:

$ sudo mkdir -p /usr/share/tomcat7/.aduna/openrdf-sesame
$ sudo chown -R tomcat7 /usr/share/tomcat7/.aduna

Restart tomcat:

$ sudo service tomcat7 restart

Copy in the required WAR files:

$ sudo cp thirdPartyLibs/*.war /var/lib/tomcat7/webapps
$ sudo cp eccService/target/EccService-2.2.war /var/lib/tomcat7/webapps

Copy in the owlim-lite jar:

$ sudo cp thirdPartyLibs/*.jar /var/lib/tomcat/webapps/EccService-2.2/WEB-INF/lib

Restart tomcat:

$ sudo service tomcat7 restart

Glassfish

Glassfish may be used as an alternative to Tomcat.

1. Update Glassfish Java permissions for socket access using vagrantConf/glassfish/java.policy file
2. Copy the following JARs from eccService/target/EccService-2.2/WEB-INF/lib/ into Glassfish /lib/endorsed folder for Logback library support:

• logback-core-1.1.2.jar
• logback-classic-1.1.2.jar
• jul-to-slf4j-1.7.6.jar

1. Configure Glassfish support for Logback libraries by using the files in the thirdPartyConfig/glassfish folder to update the following files:

• <Glassfish home>/glassfish/domains/domain1/config/logback.xml
• <Glassfish home>/glassfish/domains/domain1/config/logging.properties
• <Glassfish home>/glassfish/domains/domain1/domain.xml

1. Edit the LOG_DIR variable definition in the eccService/src/main/resources/logback.xml or WEB-INF/classes/logback.xml file to set the location of the EXPERImonitor log file.
2. Start the default Glassfish domain and database.
3. Deploy the two WAR files from the thirdPartyLibs folder and eccService/target/EccService-2.2.war.
4. Copy the owlim-lite jar from thirdPartyLibs into the WEB-INF/lib folder of the unpacked EXPERImonitor service.
5. Restart glassfish.

You should see the EXPERImonitor dashboard running on: e.g. http://localhost:8080/EccService-2.2. The OpenRDF workbench should be available on e.g. http://localhost:8080/openrdf-workbench/ (the port numbers depend on your installation choices).

If you deployed the Dashboard correctly, you should see EXPERImonitor Service Configuration page in your browser:

You are now ready to configure EXPERImonitor and start a new experiment. For further instructions please go to Using the EXPERImonitor Dashboard section.

EXPERImonitor default configuration

The EXPERImonitor configuration can be changed using the GUI presented above. However, if you want to change the default locally stored configuration then you need to edit the application.properties file. If you are building from the source release you can find this file in eccService/src/main/resources. If you have the binary release or an already deployed service you can find the file in the WEB-INF/classes folder of the unpacked EXPERImonitor service. You may need to restart your EXPERImonitor service once the file has been edited.