H-DOSE installation HOW-TO

Disclaimer

The H-DOSE platform is autonomously developed by the e-Lite research group at the Politecnico di Torino. Since the main goals of the e-Lite group are related to research purposes, the platform is given as is, without any formal or official support service. A set of HOW-TOs and research papers are made available by the developing team, together with the complete Javadocs for the platform APIs. There also some examples included in the published documentation.

For any problems concerning the installation of the H-DOSE platform, any undetected bugs, etc. please post a message onto the H-DOSE users mailing list. For developers there is also another active mailing list which is more concerned with the development of platform components and modules.
Anyway, for urgent questions, please feel free to contact directly the authors at their e-mail addresses.

Hardware requirements

The H-DOSE platform is completely developed with Java technologies, therefore it can be run on whatever device running a Java Runtime Environment v1.4.2. However since some of the processes accomplished by the platform are computationally expensive, it is recommended to use systems having at least a computational power similar to a PentiumIII machine equipped with at least 256 MBytes of RAM. We have some evidence that the platform could be run on machines with lower computational power, however some processes, the indexing process in particular, become too slower in order to be useful.

Getting started

The H-DOSE platform is mainly composed of a jar file, a couple of web services deployed as *.jws files by means of the Apache Axis framework and a set of maintenance and management java server pages. In order to get started with the platform you need to:

If not already installed, download a Java Development Kit (JDK 1.4.2 is recommended)
Download the Tomcat Servlet container from the Apache Jakarta web site (any of the 5.0.x releases should let H-DOSE work, newer versions have not yet been thoroughly tested).
Download the Apache Axis framework from the Apache Axis web site.
Access to an account on a PostgreSQL database server (alternatively you may install PostgreSQL on your machine).
Download the H-DOSE installer this web site. (download section)

Once you have downloaded all required resources, you can start the installation process.

Getting a Tomcat running on your machine.

You probably have downloaded the installation files for Tomcat from the Apache Jakarta web site;
the Tomcat servlet container requires the presence of a Java Runtime Environment on the machine where it will be running, therefore if you haven't already installed the JDK it is now time to do it.
Please follow the installer indications in order to get a fully functional Java environment on you machine.
Ok, now you have to proceed with the installation of Tomcat.

Win32

In the win32 version, Tomcat comes as a self-installer package that can be run by double-clicking the installer filename. All versions of Tomcat are suitable for deploying the H-DOSE platform, starting from the 4.0 version. However all our tests are deployed using a Tomcat 5.0 (the 5.5 is currently under testing, too - the newest jaxrpc and xerces libraries seem to cause some conflict).
The only two things that you have to pay attention to, during the installation process, are the location in which Tomcat will be installed and the kind of server startup is required: in order to allow H-DOSE to properly work on your new Tomcat server you need to specify a location name that does not contain spaces or special characters like -§,°,£,&,... This is mainly due to the agent-based part of the platform, which is deployed usign the Jade framework.

Secondly, depending on the use you may want to do of the platform, you should set the correct type of installation for Tomcat, which can be either as a service or as a standalone application. In general, if you are deploying a set of web applications and you also plan to use the H-DOSE platform as semantic middleware, it is recommended to install Tomcat as a service, instead, if your are developing applications and you need frequent restarts of the servlet container it should be useful to select a standalone installation.

Anyway you can find more information about the Java installation and the Tomcat installation at their respective sites:

Linux

At first you should check if the Tomcat package is available for your specific distribution, in that case you should check that the java virtual machine active on your system is the one from Sun. As an example, with Debian GNU/Linux (and derivatives, like Ubuntu) the Tomcat packages depends on a JVM and a java complier, but Sun's JVM is not present in Debian: without user intervention will be installed and used the kaffe JVM or GNU gcj/gij. We have not tested if H-HOSE will work on these configurations. On Debian you could either add a repository for a Sun JVM (see blackdown.org for instructions), create a Debian package, or install directly the Sun JVM. Then, using the update-alternatives mechanism, make the system use the Sun JVM.

In case there are no packages for your distribution, you can download the Tomact servlet container from the Jakarta Web site.

Install Apache Axis

For a complete guide on Apache Axis Installation, please check the official installation page at:

http://ws.apache.org/axis/java/install.html.

Once you have downloaded the Axis archive from this site, it should be sufficient to copy the axis directory from the downloaded archive into the Tomcat webapps directory.

You may verify that Axis is operative by running the Tomcat server and then exploring the http://localhost:8080/axis/happyaxis.jsp page. If any library is missing, we recommend to download and install it in into the shared directory of Tomcat

%CATALINA_HOME%/shared/lib/

As we will soon see, all the libraries required by H-DOSE will be installed (copied) into the same shared folder. Be warned that a few libraries may be overwritten. This should guarantee compatibility between H-DOSE and Axis/Tomcat.

Getting a PostgreSQL running on your machine

Win32

From few months ago, also the Windows users have the ability to natively run a PostgreSQL server, without the heavy burden of setting up PostgreSQL under Cygwin. There is, in fact, a version of the PostgreSQL v8.0 that comes with a fully functional, user friendly, Windows installer, therefore if you are a Windows geek, then you have the possibility to run PostgreSQL in the usual Windows style, possibly without crashes.

You only need to download the installer from the PostgreSQL site.

H-DOSE installation

The installation of the H-DOSE platform is organized as follows.

Stop the execution of your tomcat server;
Launch the H-DOSE installer:
java -jar install.jar
Follow the installer instructions;
Once ended the installer execution, makes sure that tomcat has write access to the H-DOSE installation directory;
Restart Tomcat;
Point your browser at the H-DOSE location, something similar to:
http://localhost:8080/axis/hdose
Follow the indications reported in the visualized pages for finalizing the installation;
For further information see the README file that comes with the installer file.

The DoseAgency module

To start-up the Dose Agency module open your preferred browser and navigate to the DoseAgency.jsp page.
This page initializes the Dose Agency requiring the specification of some functional parameters:

Central Agency Host: The server that will host the Dose Agency. The full name must be specified here, e.g.: myserver.mydomain.net instead of localhost. Under Windows you may wish to add a row in the file C:\WINDOWS\System32\Drivers\etc\hosts specifying the server IP and its (real or fictitious) full name.
AnnotationWS endpoint: The URL of the Annotation Repository Web Service http://hdosehost:8080/axis/AnnoRepositoryWS.jws.
ExpanderWS endpoint: The URL of the Expander Web Service "http://hdosehost:8080/axis/ExpanderWS.jws".
SearchWS endpoint: The URL of the Search Engine Web Service "http://hdosehost:8080/axis/SearchEngineWS.jws".
Autonomic Delay: The minimum interval of time (minutes) that can occur between two successive starts of the platform auto-check processes.
StopWords file URL: The location were the file of language dependent stopwords is accessible, usually "http://hdosehost:8080/axis/stopwordDictionary.xml".
Ontology file URL: The location were the H-DOSE ontology could be accessed, usually "http://hdosehost:8080/axis/ontology.owl"
DB uri: The URI of the database in which data should be stored, usually "jdbc:postgresql://dbservername/dbname/" (see also the notes above about the initialization of the PostgresSQL server).
DB user: The user you configured on PostgreSQL to own the H-DOSE database tables.
DB password: The password of the user that owns H-DOSE tables.
DB driver: The jdbc driver used to access PostgreSQL, if you are not a developer, leave it as "org.postgresql.Driver".
EndPoint: The servers running H-DOSE or providing containers for the deployment of platfrom agents, usually in the form "http://agencyhost:8080/axis/ContainerProviderWS.jws"

When all the parameters have been inserted, the Start Agency button launches the agent platform of H-DOSE, and, by doing so, the platform becomes ready to provide answers to automatic indexing requests...

We hope you will enjoy our effort and please, if you find any bugs or if you have comments or suggestion write to the HDOSE users mailing list.