Installation: Source Code

Karma is a Web-based application. You can run Karma on a single machine, running both the server and the client on the same machine (this is the usual way to run Karma). You can also install Karma on a server and use it on different machines.

Topics:

• System Requirements
• Downloading
• Compiling
• Compiling in Offline Mode
• Running Karma
• Warnings
• Running Karma in Vagrant(Currently available in development branch only)

System Requirements

Karma is written in Java and will run on Mac, Linux and Windows. To install Karma you need:

• Java 1.7
  • Download from http://www.oracle.com/technetwork/java/javase/downloads/index.html
  • Make sure JAVA_HOME environment variable is pointing to JDK 1.7
• Maven 3.0
  • Make sure that M2_HOME and M2 environment variables are set as described in Maven Installation Instructions: http://maven.apache.org/download.cgi
• An internet connection so that Maven can download the needed libraries
• A Web browser: we recommend Chrome, Safari or Firefox, but Karma will also run on Internet Explorer.

Downloading

If you are new to GitHub and just want to download Karma, then get the zip file: https://github.com/InformationIntegrationGroup/Web-Karma/archive/master.zip. If you know GitHub, you know that you can also clone or fork the repository.

Compiling and Installing Karma

You need to compile Karma, but this is easy to do with Maven:

1. Unpack your zip file in whatever directory you want (use one that you can easily get to from your command line).
2. Open a shell (command prompt) and go to the directory where you put Karma.
3. On the shell prompt type mvn clean install. This will compile and install Karma. It may take a couple of minutes the first time because maven will download many libraries (you need an internet connection for this to work). You can also skip the tests by executing mvn clean install -Dmaven.test.skip=true.
4. If all goes well, your screen should look something like this:

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] 
[INFO] ISI Karma Maven Webapp ............................ SUCCESS [0.318s]
[INFO] karma-util ........................................ SUCCESS [2.184s]
[INFO] karma-crf ......................................... SUCCESS [0.406s]
[INFO] karma-cleaning .................................... SUCCESS [1.395s]
[INFO] karma-common ...................................... SUCCESS [2.426s]
[INFO] karma-commands .................................... SUCCESS [0.010s]
[INFO] commands-common ................................... SUCCESS [0.212s]
[INFO] karma-jdbc ........................................ SUCCESS [0.172s]
[INFO] karma-not-common .................................. SUCCESS [0.355s]
[INFO] commands-update ................................... SUCCESS [0.278s]
[INFO] commands-alignment ................................ SUCCESS [0.467s]
[INFO] commands-worksheet ................................ SUCCESS [0.435s]
[INFO] commands-python ................................... SUCCESS [0.727s]
[INFO] commands-alignment-openrdf ........................ SUCCESS [0.305s]
[INFO] commands-cleaning ................................. SUCCESS [0.187s]
[INFO] commands-publish .................................. SUCCESS [0.192s]
[INFO] commands-publish-jdbc ............................. SUCCESS [0.061s]
[INFO] commands-publish-alignment-openrdf ................ SUCCESS [0.322s]
[INFO] commands-update-jdbc .............................. SUCCESS [0.126s]
[INFO] commands-import ................................... SUCCESS [0.013s]
[INFO] import-common ..................................... SUCCESS [0.182s]
[INFO] import-csv ........................................ SUCCESS [0.173s]
[INFO] import-database ................................... SUCCESS [0.210s]
[INFO] import-excel ...................................... SUCCESS [0.141s]
[INFO] import-file ....................................... SUCCESS [0.050s]
[INFO] import-ontology ................................... SUCCESS [0.122s]
[INFO] import-json ....................................... SUCCESS [0.116s]
[INFO] import-service .................................... SUCCESS [0.154s]
[INFO] import-spatial .................................... SUCCESS [0.469s]
[INFO] import-xml ........................................ SUCCESS [0.122s]
[INFO] commands-include .................................. SUCCESS [0.014s]
[INFO] karma-web ......................................... SUCCESS [14.025s]
[INFO] karma-offline ..................................... SUCCESS [17.332s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 44.119s
[INFO] Finished at: Fri Apr 25 23:07:55 PDT 2014
[INFO] Final Memory: 62M/605M
[INFO] ------------------------------------------------------------------------

Note: you only need an internet connection to compile Karma after you download it. Once it is compiled, you can run it without an internet connection.

Compiling and Installing Karma in Offline Mode

You can request ISI for a Karma DVD that include the Web-Karma zip and all the included libraries. You need to compile Karma, but this is easy to do with Maven:

1. Unpack your Web-Karma zip file in whatever directory you want (use one that you can easily get to from your command line).
2. Copy the mvn folder from the DVD to your ~/.m2 (Your Maven repository)
3. Open a shell (command prompt) and go to the directory where you put Karma.
4. On the shell prompt type mvn clean install. This will compile and install Karma.
5. If all goes well, your screen should look something like this:

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] 
[INFO] ISI Karma Maven Webapp ............................ SUCCESS [0.318s]
[INFO] karma-util ........................................ SUCCESS [2.184s]
[INFO] karma-crf ......................................... SUCCESS [0.406s]
[INFO] karma-cleaning .................................... SUCCESS [1.395s]
[INFO] karma-common ...................................... SUCCESS [2.426s]
[INFO] karma-commands .................................... SUCCESS [0.010s]
[INFO] commands-common ................................... SUCCESS [0.212s]
[INFO] karma-jdbc ........................................ SUCCESS [0.172s]
[INFO] karma-not-common .................................. SUCCESS [0.355s]
[INFO] commands-update ................................... SUCCESS [0.278s]
[INFO] commands-alignment ................................ SUCCESS [0.467s]
[INFO] commands-worksheet ................................ SUCCESS [0.435s]
[INFO] commands-python ................................... SUCCESS [0.727s]
[INFO] commands-alignment-openrdf ........................ SUCCESS [0.305s]
[INFO] commands-cleaning ................................. SUCCESS [0.187s]
[INFO] commands-publish .................................. SUCCESS [0.192s]
[INFO] commands-publish-jdbc ............................. SUCCESS [0.061s]
[INFO] commands-publish-alignment-openrdf ................ SUCCESS [0.322s]
[INFO] commands-update-jdbc .............................. SUCCESS [0.126s]
[INFO] commands-import ................................... SUCCESS [0.013s]
[INFO] import-common ..................................... SUCCESS [0.182s]
[INFO] import-csv ........................................ SUCCESS [0.173s]
[INFO] import-database ................................... SUCCESS [0.210s]
[INFO] import-excel ...................................... SUCCESS [0.141s]
[INFO] import-file ....................................... SUCCESS [0.050s]
[INFO] import-ontology ................................... SUCCESS [0.122s]
[INFO] import-json ....................................... SUCCESS [0.116s]
[INFO] import-service .................................... SUCCESS [0.154s]
[INFO] import-spatial .................................... SUCCESS [0.469s]
[INFO] import-xml ........................................ SUCCESS [0.122s]
[INFO] commands-include .................................. SUCCESS [0.014s]
[INFO] karma-web ......................................... SUCCESS [14.025s]
[INFO] karma-offline ..................................... SUCCESS [17.332s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 44.119s
[INFO] Finished at: Fri Apr 25 23:07:55 PDT 2014
[INFO] Final Memory: 62M/605M
[INFO] ------------------------------------------------------------------------

Running Karma

Karma needs a lot of memory. We recommend at least 4GB when working with ontologies containing over 100 classes and properties. The Configuration page explains how to set up the memory for Karma.

To run Karma:

1. Change to the karma-web sub-directory by executing cd karma-web in the shell (command prompt).
2. If running Karma on a windows machine, edit src\main\webapp\WEB-INF\web.xml. Search "Uncomment this for Windows" and uncomment the <servlet> tag under the comment. This is how your web.xml should look like:

  <servlet>
  	<servlet-name>R2RMLMappingTripleStoreServlet</servlet-name>
  	<servlet-class>edu.isi.karma.webserver.R2RMLMappingTripleStoreServlet</servlet-class>
  </servlet>
  
  <!-- Uncomment this for Windows, This is to fix an issue with
  Jetty opening files using memory map in Windows that creates lock
  and then Karma cannot overwrite those files -->
  <servlet>
     <servlet-name>default</servlet-name>
     <servlet-class>org.eclipse.jetty.servlet.DefaultServlet</servlet-class>
     <init-param>
       <param-name>useFileMappedBuffer</param-name>
       <param-value>false</param-value>
     </init-param>
     <load-on-startup>1</load-on-startup>
   </servlet>
      
  <servlet-mapping>
    <servlet-name>KarmaServlet</servlet-name>
    <url-pattern>/KarmaServlet</url-pattern>
  </servlet-mapping>

1. Start the server part of Karma by typing mvn jetty:run in the shell.
2. Wait until you see the [INFO] Started Jetty Server in the shell.
3. Open a Web Browser and go to page http://localhost:8080.

In summary:

cd karma-web
mvn jetty:run

Note: once the server is running, you can also reload the page to start a fresh copy of Karma (you don't need to restart the server part).

You should see a page that looks like this (your version number will be different):

Now that you know your Karma installation is working, you may want to configure it so that you can work with large sources without running out of memory, load ontologies automatically and understand where Karma saves your files. See Configuration.

Running Karma on a Different Port

By default, Karma runs on port 8080. You can specify the port number in the command to start the Jetty server as in

mvn -Djetty.port=9999 jetty:run

Running Karma with Logging Turned On

To start in logging mode (where all the logs are stored in the log folder), use the following command to start the server:

mvn -Dslf4j=false -Dlog4j.configuration=file:./config/log4j.properties jetty:run

Are the Warnings Normal?

The following warnings are normal and we have yet to eliminate them. If you see them, they are expected (your help fixing these would be greatly appreciated):

[WARNING] 
[WARNING] Some problems were encountered while building the effective model for edu.isi:webkarma:war:0.0.1-SNAPSHOT
[WARNING] 'dependencies.dependency.systemPath' for weka:weka:jar should not point at files within the project directory, ${project.basedir}/lib/weka.jar will be unresolvable by dependent projects @ line 100, column 18
[WARNING] 'dependencies.dependency.(groupId:artifactId:type:classifier)' must be unique: com.healthmarketscience.jackcess:jackcess:jar -> version 1.2.10 vs 1.2.4 @ line 176, column 21
[WARNING] 'dependencies.dependency.systemPath' for uk.ac.shef.wit.simmetrics:simmetrics:jar should not point at files within the project directory, ${project.basedir}/lib/simmetrics_jar_v1_6_2_d07_02_07.jar will be unresolvable by dependent projects @ line 242, column 19
[WARNING] 'dependencies.dependency.systemPath' for com.jspsmart.upload:jspsmartupload:jar should not point at files within the project directory, ${project.basedir}/lib/jsmartupload.jar will be unresolvable by dependent projects @ line 259, column 19
[WARNING] 'build.plugins.plugin.version' for org.apache.maven.plugins:maven-compiler-plugin is missing. @ line 374, column 16
[WARNING] 
[WARNING] It is highly recommended to fix these problems because they threaten the stability of your build.
[WARNING] 
[WARNING] For this reason, future Maven versions might no longer support building such malformed projects.
[WARNING] 

The following warning is also normal:

2013-05-13 23:31:17.278:INFO:oejs.Server:jetty-8.0.3.v20111011
2013-05-13 23:31:19.202:INFO:oejpw.PlusConfiguration:No Transaction manager found - if your webapp requires one, please configure one.

If things go wrong, check the Troubleshooting Page