ADEQUATE : Installation guides

Created by Václav Brodec, last modified on Jun 01, 2017

Odalic platform consists of three main components: the server application (Odalic Semantic Table Interpretation), the web client (Odalic UI), and finally the Odalic UnifiedViews plugin. Both the web client and the plugin require a running server to work properly.

Server installation

Prerequisites

  • at least 4 GB RAM
  • Java Runtime Environment version 8+
  • Apache Tomcat servlet container version 8+
  • Apache Maven 3 (to build and install from the source files)
  • running SMTP server (optimally allowing secure communication) in order to send confirmation e-mails (optional)

The server is platform independent and runs on any major operating system supporting Java Runtime Environment.

Deployment

There are basically two ways to install the server application: the user can either use a prepared web archive (WAR) from the the installation disc, or compile the server web archive file from the provided source files. In both cases the produced WAR file is to be deployed in a running Apache Tomcat instance.

Apart from the web archive, the server also needs access to a separate working directory {sti.home} with subdirectories config and resources. Its default version can be also obtained from the root of server source repository (files and directories other than config and resources are meant to build the project and are not needed in the working directory) or copied directly from the installation disc.

The Java Virtual Machine running the Tomcat itself has to be started with a system property cz.cuni.mff.xrg.odalic.sti set to a path leading to the main configuration file, e.g.:

 -Dcz.cuni.mff.xrg.odalic.sti={sti.home}/config/sti.properties

where the {sti.home}/config/sti.properties is a location of the main configuration file.

The details of configuration are described in section Configuration, the minimum needed settings are the following (located in the main configuration file config/sti.properties):

  • sti.home - absolute path to the root working directory {sti.home}.
  • cz.cuni.mff.xrg.odalic.users.admin.email - default (admin) user email (used as login)
  • cz.cuni.mff.xrg.odalic.users.admin.password - default (admin) user password (can be changed later using the API)
  • cz.cuni.mff.xrg.odalic.db.file - absolute path to a file (which will be created if not existing yet) keeping the state of the server

In the config/websearch.properties, set the authorization token at bing.key to the Bing Web Search service, which can be obtained at https://azure.microsoft.com/cs-cz/services/cognitive-services/search/.

Apart from these every used knowledge base (the source of Linked Data resources) has to be configured separately. More in Configuration.

Building from source files

  1. Checkout the sources and accompanying resource from Git repository at https://github.com/odalic/sti or copy them from the installation disc.
  2. Install the libraries in the lib directory by running the mvninstall.bat in the source files root directory (or in case of other OSs than Windows: running the few mvn commands present there manually), as these are not present in any public Maven repository.
  3. Run mvn install in the root directory, all the sub-projects will be installed one by one and the produced .war will be placed in odalic/target subdirectory.
  4. Copy the subdirectories config and resources (only these are needed during runtime) at a desired location and make the necessary changes in the main configuration file sti.properties, located in the config sub-directory and follow the rest of Deployment section.

Building Javadoc documentation

The Javadoc documentation building is supported only for the odalic module of the server. To do that, navigate to source files repository subdirectory odalic and run mvn javadoc:javadoc to build the Javadoc files hirararchy in odalic/target/site or mvn javadoc:jar to generate a JAR packed Javadoc in the target. In any case, the installation disc already contains pre-generated Javadoc.

Security

While the application provides means to secure privileged operations according to JWT standard (JSON Web Tokens, more in Authentication and authorization), the requests exchanged between a client and the server are still vulnerable to eavesdropping and/or tampering. To prevent man-in-the-middle attack, we recommend using Transport Layer Security (TLS) protocol as a way of communicating with the server.

The server needs to be configured individually. If you are using Apache Tomcat, we recommend following the guidelines described on the official site https://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html. If you do decide to use the TLS protcol, a web client should be configured accordingly (see Web client installation section below).

Confirmation e-mails set up

In the default configuration the confirmation e-mails, which require the user to confirm the sign-up and password-changing process by following a sent hyperlink, are turned off by option mail.confirmations = false in the sti.properties. If the administrator chooses to the turn them on by setting the option to true, he or she has to set up the other options starting with mail. The confirmation e-mails require an already existing running SMTP server that the application can connect to using the provided mail options such as username, password, host, SMTP port and used standard socket factory (the one using encrypted connections is in the defaults, but can be left out when unprotected connection is used). The installation files already contain tested configuration using email.cz as example of a common freemail provider (sans the password and login).

If the mail is not properly configured the sign-up user may not obtain the required confirmation links, thus preventing them from using the application at all.

Web client installation

The web client, being a single page application, works almost "out of the box", if a proper browser, with HTML5 support and JavaScript enabled, is used. However, to ensure the best experience, steps mentioned below should be followed:

Setting up a web server for the web client

The web client should reside in a web server of your choice. The server API in the default setting allows to make cross-origin requests. In order to mitigate the risk of exploitation or in case of any troubles concerning the Same-origin policy protection, modify the appropriate headers in CorsResponseFilter.java from the server source, according to the location of your client instance and recompile the server. This is a good place though to remind you NOT to use or rely on Odalic in situations when your money and life would depend on it!

Configuring the sign-up and password-reset confirmation address on the server

Specified in detail in Configuration section, the following properties need to be correctly configured in the main configuration file, sti.properties, if you want to use the default web client application to respond to the confirmation URLs:

  • cz.cuni.mff.xrg.odalic.users.signup.url - URL of the sign-up confirmation link (received by a user on a provided e-mail address during sign-up process)
  • cz.cuni.mff.xrg.odalic.users.reset.url - URL of the password-reset confirmation link (received by a user on his/her previously registered e-mail address)

In case you are using the default web application, different web client's screens are accessible by visiting URL .../index.html#/screenname, screenname being name of the screen visited, and index.html being entry point of the web client application.

The token received for sign-up confirmation is processed at .../index.html#/signup/token, while the token for password-reset is handled at .../index.html#/chngpasswd/token (token being the actual token). Therefore an exemplary relevant fragment of the configuration may look like this (we assume the web client is accessible at URL http://localhost:8080/, or, more specifically, at http://localhost:8080/index.html):

# URL format for a sing-up confirmation.
cz.cuni.mff.xrg.odalic.users.signup.url=http://localhost:8080/index.html#/signup/%s
# URL format for a password setting confirmation.
cz.cuni.mff.xrg.odalic.users.reset.url=http://localhost:8080/index.html#/chngpasswd/%s

Naturally if you roll your own application based on the Odalic server, you are free to provide entirely different formatting strings for the URLs (as long as they are valid and contain the place-holder %s to place the generated token in).

Configuring address of the server in the client

Assume the ./odalic-ui/ is a path of the folder the web client application is located at.

Open ./odalic-ui/config.txt file in a text editor. Locate the following piece of code:

[server]
address=http://localhost:8080/odalic/

Replace it with the following lines of code:

[server]
address=ActualServerAddress

Where ActualServerAddress is the actual server address, for example http://localhost:8080/.

Note that if the server uses TLS protocol as a way of securing communication with the client, https:// should be used instead of http://.

Installing LodLive application component

The web client uses optional LodLive application component as its RDF resource browser for supported knowledge bases.

  1. Let's assume the ./odalic/odalic-ui/ is a path of the folder the web client application is located at.
  2. Navigate to ./odalic/ folder.
  3. Copy the LodLive directory from the installation disc or checked-out from the repository hosting the version modified to work with Odalic UI and paste it in ./odalic/ folder.

Supported browsers

The web client can be accessed using any of the popular internet browsers with HTML5 support. Additionally, it is necessary for the browser to support SVG elements.

Some of the supported browsers are:

  • Microsoft® Internet Explorer 11
  • Microsoft® Edge 14 (and newer)
  • Mozilla Firefox 50 (and newer)
  • Google® Chrome 49 (and newer)

Plugin installation

Deployment

As described in Dealing with OSGi dependency issues when DPU is imported, UnifiedViews plugins are packed as OSGi bundles and as such they contain their dependences in embedded JARs or declare them in their manifest. In the latter case it is the user's obligation to make them available to the chosen OSGi container. Apart from UnifiedViews version accepting plugins of version 2.1.7, the Odalic plugin requires the following:

Copy them from the installation disc (or download them from the URLs) to lib sub-directory at the path specified with key module.path in the UnifiedViews frontend configuration.

Follow the instructions to create DPU Template at DPU Template Creation, where the uploaded file will be the t-odalic-{version}.jar from the installation disc or the one built from the source files as described in the following section. To set up the template, follow the instructions in the plugin user manual.

Building from source files

  1. Checkout the sources from Git repository at https://github.com/odalic/odalic-uv-plugin or copy them from the installation disc.
  2. Run mvn package in the t-odalic directory and the produced t-odalic-{version}.jar OSGi plugin bundle will be placed in t-odalic/target directory.