Getting started with the ECC

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

Acquiring the required 3rd party libraries

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

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

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 ECC distribution

ECC dependencies and licenses

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

<ECC 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 ECC service using Vagrant

The quickest method of building and deploying the ECC 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 ECC for you. Once you have acquired the ECC 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 ECC root directory:

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

4. Open a command line in the root directory and enter ‘vagrant up’

Once the installation process is complete, you will be able to access the ECC dashboard by pointing your web browser to the URL presented in the console.

Building the ECC manually

Pre-requisites

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

• Java JDK 1.7 (Oracle JDK for Windows and OpenJDK for Ubuntu have both been tested)
• Maven 3.0

Install these tools according to their instructions for your platform.

Building

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

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

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

eccService/target/EccService-2.1.war

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

spring:boot

A fast way of deploying the ECC 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 ECC 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 ECC 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 ECC 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 ECC 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 ECC is set up by default to use this local address.

PostgreSQL

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

The default login details used by the ECC 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 ECC (see below).

The database schema is defined in the edm/resources/edm-metrics-postgres.sql file of the ECC 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 ECC 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 ECC 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 ECC service by copying the two WAR files from the thirdPartyLibs folder and eccService/target/EccService-2.1.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 ECC service TODO where? Then restart the Tomcat service.

You should see the ECC dashboard running on: http://localhost:8080/EccService-2.1

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.1.war /var/lib/tomcat7/webapps

Copy in the owlim-lite jar:

$ sudo cp thirdPartyLibs/*.jar /var/lib/tomcat/webapps/EccService-2.1/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.1/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 ECC 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.1.war.
4. Copy the owlim-lite jar from thirdPartyLibs into the WEB-INF/lib folder of the unpacked ECC service.
5. Restart glassfish.

You should see the ECC dashboard running on: e.g. http://localhost:8080/EccService-2.1. 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 ECC Service Configuration page in your browser:

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

ECC default configuration

The ECC 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 ECC service. You may need to restart your ECC service once the file has been edited.