Setting up an Alignment Server

The Alignment server is an online service on which alignments may be manipulated (created, modified, displayed). In order to persistently store alignments, it has to be coupled to a storage service, such as a database.

An extensive presentation of the Alignment API can be found at https://moex.gitlabpages.inria.fr/alignapi/ including a description of the Alignment server. We also have an on-line tutorial on using it through the server.

Requirements

The Alignment server is usually paired with a storage service such as an SQL database server. We see here how to use mysql or Postgres.

Although there is support for alignment servers without persistent storage, at the moment, using a data base is compulsory (contact us if you want this to be different).

Creating the database for MySQL / MariaDB

In order to use the Alignment server, it is necessary to create its database. This can simply be done as a DB administrator by the following instructions:

$ mysql -u root -p sql> CREATE DATABASE AServDB; sql> GRANT ALL PRIVILEGES ON AServDB.* TO adminAServ@localhost IDENTIFIED BY 'aaa345'; sql> quit
The database schema will be created upon the first launch of the server.

Creating the database for Postgres

This can be achieved similarly, as a database administrator by:

$ sudo -i -u postgres $ psql postgres# CREATE DATABASE "AServDB"; postgres# CREATE USER "adminAServ" WITH PASSWORD 'aaa345'; postgres# GRANT ALL PRIVILEGES ON DATABASE "AServDB" TO "adminAServ"; postgres# \q
or alternatively:
$ sudo -i -u postgres $ createuser -P --interactive adminAServ $ createdb -O adminAServ -E UTF-8 AServDB

Of course, you are advised to use different user, password and database name. This can be achieved either:

Launching the Alignment server

The Alignment server requires that the corresponding database management system server be running. In our case, this can be achieved through:

$ service mysql start
or
$ service postgresql start

Running the Alignment server is achieved through (use the corresponding options):

$ java -jar lib/alignsvc.jar -H
The Alignment server is then available through HTTP with:
http://localhost:8089/html/

The possible switches to the server launcher are:

$ java -jar lib/alignsvc.jar -h usage: java fr.inrialpes.exmo.align.service.AlignmentService [options] Launch an Alignment server Options: -A,--jade Launch JADE service (with port PORT; default 8888) -B,--dbms <DBMS> Use DBMS system (mysql,postgres; default: mysql) -b,--dbmsbase <BASE> Use DBMS BASE (default: AServDB) -d,--debug debug argument is deprecated, use logging instead -D <NAME=VALUE> Use value for given property -h,--help Print this page -H,--http Launch HTTP service (with port PORT; default 8089) -i,--impl <CLASS> Launch service corresponding to CLASS -l,--dbmsuser <USER> Use DBMS USER (default: scott) -m,--dbmshost <HOST> Use DBMS HOST (default: localhost) -o,--output <FILE> Send output to FILE -O,--oyster Register to Oyster directory -P,--params <FILE> Read parameters from FILE -p,--dbmspass <PASS> Use DBMS PASSword (default: tiger) -S,--host <HOSTNAME> Set the HOSTNAME of the server -s,--dbmsport <PORT> Use DBMS PORT (default: null) -u,--uriprefix <URI> Set alignment URIs with prefix URI -W,--wsdl Launch Web service (with port PORT; default 7777) -x,--nossl Use without ssl (only for test purpose) -X,--jxta Launch JXTA service (with port PORT; default 6666) Alignment server 4.10 (2223)
See also comments about using the logging mechanisms for detecting errors.

Embedding more methods in the Alignment Server

Adding new matcher, renderer, evaluators, or services in the Alignment Server, is really easy. This requires that your class be an implementation of respectively AlignmentProcess, AlignmentRenderer, Evaluator or AlignmentServiceProfile. It suffices to add all the necessary jarfiles in the MANIFEST file of the Alignment Server jarfile used to launch the server (typically alignsvc.jar) and to put these jarfiles in the same location as this last one.

For instance:

Manifest-Version: 1.0 Created-By: your.MailAddress@example.org Class-Path: alignsvc.jar olgraph.jar procola.jar Main-Class: fr.inrialpes.exmo.align.service.AlignmentService
is the required MANIFEST file for embedding our OLA algorithm which requires two jarfiles: procola.jar and olgraph.jar.

In case of a PermGem error

Because we load all classes in the path to check if they implement an API interface, this may raise a PermGem error. One solution is to increase its size with:

-XX:MaxPermSize=256m
in the command line. Another solution would be to reduce the number of Jarfiles and classes in the path.

Launching the server with Oyster registery (legacy)

The Alignment API is already compiled with Oyster support. However, it is not ready to be launched. The instructions to do so are:

  1. get the Oyster2 package from http://ontoware.org/projects/oyster2
  2. copy the four libraries in lib/ (or at least in the classpath)
  3. copy the O2serverfiles directory
  4. copy the "new store" config file
  5. edit the "new store" config file for it to use the correct environent
  6. launch kaon2.jar:
    $ java -cp lib/kaon2.jar org.semanticweb.kaon2.server.ServerMain -registry -rmi -ontologies O2serverfiles
    (use -registryport for using another port than 1099, then the "new store" configuration file must be edited)
  7. launch the server:
    $ java -jar lib/alignsvc.jar -O -d4

Ports used by the Alignment Server (by default)

The Alignment server is a communicating system that communicates through TCP sockets which are bound to ports on your machines. We provide here the list of default ports and options to change them as well as the necessity for the firewalls to open these ports:

defaultoptionopen?
HTTP/REST8089-HY
MySQL3306--dbmsportN (if on the same machine)
PostGres5432--dbmsportN (if on the same machine)
Jade8888-A
//1099? (RMI)
7778Y (MTP HTTP)
WSDL7777-WY
JXTA6666-PY
Oyster1099-OY (RMI/Kaon2)

Of course, the ports need only to be open if there is an access from the outside to the server with the corresponding plug-in. The only compulsory ports for the server is the MySQL one. Both Jade and Oyster/Kaon2 use rmi connection and the default 1099 port. Moreover, concerning Oyster, this port must be open to the outside.

Configuring an Apache frontend

It may be convenient to provide access to a server through an Apache server proxy. For that purpose some tweaking is necessary:

$ a2dissite default $ a2dissite default-ssl $ a2enmod proxy $ a2enmod proxy-http $ service apache2 restart

Setting up a back-up for the database

Sample backup of the server content (MySQL):

$ /usr/local/mysql/bin/mysqldump -u adminAServ -paaa345 AServDB > AServBackup.sql
And restoring:
$ /usr/local/mysql/bin/mysql -u adminAServ -paaa345 AServDB sql> source AServBackup.sql;

For Postgres:

$ pg_dump [-W -U adminAServ] AServDB -f AServBackup.sql
And restoring:
$ psql [-W -U adminAServ] < AServBackup.sql


https://moex.gitlabpages.inria.fr/alignapi/aserv.html