Home/ Installation Manual

Installation Manual

1. Introduction and dependencies

2. Installing required software

2.1 Windows

2.1.1 Ready-to-go installation 2.1.2 Detailed installation

2.2 MacOS X

2.3 Linux

3. Installing MHK

4. Troubleshooting

1. Introduction and Dependencies

MHK is a web application that runs inside a special software called web server. It's currently developed on Mac OS X and is tested in Windows XP/Vista and Linux.

In order to run MHK on you computer you need to install, if not yet, the following software:

• JAVA Virtual Machine (1.4 or later)

The interface of MHK is written in Java and requires the Java Virtual Machine. It is sufficient to have the minimal installation, that does not contain the development tools, also known as the Java Runtime Environment (JRE). The Java virtual machine is preinstalled in Macintosh computers and is part also of the standard installation in many Linux distributions. On Windows systems it is necessary to install the Java Virtual Machine.

• Apache Tomcat Webserver

MHK requires an web server capable of hosting a Java written web application (servlet). Tomcat is the reference implementation of Java enabled web servers. Other Servlet capable web servers, like Jetty, should run MHK.

• MySQL Database

MHK uses a relational database to store the information converted from Historical Sources.

• SWI Prolog Interpreter

Prolog is a declarative programming language with special facilities for writting translators for formal languages. Inside MHK Prolog is used in the Source file translator, the software that compiles the transcriptions of historical documents into database records.

All this software is open source and it's freely available on Internet. Next chapter will cover the installation of this software on MS Windows and Unix based systems.

2. Installing Required Software

2.1 Windows

2.1.1 Ready-to-go installation

There is a ready-to-go MHK package for Windows systems from now known as "MHK Portable". The MHK Portable package is bundled with everything you need to get MHK running (Java, Tomcat, Mysql and Prolog).

Please ask for a "MHK Portable package" at joaquim@dei.uc.pt.

In order to run "MHK Portable":

• Unzip the file to your hard drive or pen disk;

• Run the MHK Portable application inside the folder. Firewall warnings will popup, please give permission to applications;

• An MHK session should start on you prefered webbrowser.

• To start and stop your MHK Installation you can right click on MHK icon on your Windows taskbar.

2.1.2 Detailed installation

• Installing the Java Virtual Machine

Download the latest version of Java Runtime Environment (JRE) from http://java.sun.com/javase/downloads/index.jsp. Click the installer and just follow the instructions.

• Installing Apache Tomcat

Download the latest version from http://tomcat.apache.org/. Under Binary Distributions you should choose "Windows Service Installer" that contains the Windows installer. When installing please make note of the Apache Tomcat installation folder. Usually it goes to C:\Program files\Apache Software Foundation\tomcat 5.0. You will need it later in order to install the MHK webapp. In configuration you can just keep the defaults as port 8080 and an empty admin password. Tomcat normally finds the installation directory of the Java virtual machine. If Tomcat asks you for the installation directory you should correct it. You can start Tomcat with

• Installing MySQL Database Server

Download the latest Windows Essentials package from http://dev.mysql.com/downloads/. You can just use the default settings. When asked about the root password either leave it empty (which is the default password) or choose a new one that you will have to put in the properties after MHK installation.

• Installing SWI Prolog

Download the windows stable version at http://www.swi-prolog.org/dl-stable.html and install it. Usually prolog goes to c:\Program files\pl and will be detected by MHK when needed. There is a message that appears related to the inability to register some entries in the windows registry

2.2 MacOS X

• Installing Apache Tomcat

Download the latest version from http://tomcat.apache.org/. Under Binary Distributions you should choose the zip package. Unzip and install it on your Applications folder. You can start Tomcat with

• Installing MySQL Database Server
• Download the latest package from http://dev.mysql.com/downloads/. Install the package, the prefPane and the startup item. Set the root password by opening a terminal and doing /usr/local/mysql/bin/mysqladmin -u root password yournewpassword.
• In recent distributions of MySQL, you can also run the script mysql_secure_installation instead of just changing the root password. That script allows you to change the root password, delete the test database, remove the anonymous user, remove remote access (allowing access from the local machine only) and reset the privileges table.
• On Leopard there seems to be some problems that have not been addressed by the official installation so far (11-11-2007). There are some instructions on how to install mySQL from source at http://hivelogic.com/narrative/articles/installing-mysql-on-mac-os-x

• Installing SWI Prolog

Download the MacOS X stable version at http://www.swi-prolog.org/dl-stable.html, unzip and install on your applications folder.

2.3 Linux

3. Installing MHK

• Installing the webapp
1. Stop Apache Tomcat Server (see "Installing Required Software" for more information).
2. MHK comes on a zipped mhk.war file you should decompress.
3. Locate your Tomcat installation folder (see "Installing Required Software" for more information) and put the .war under the "webapps" folder.
4. Restart Tomcat server.
5. On your web browser go to http://localhost:8080/mhk. You should see the MHK Welcome Screen. Now it's time to set up a database.

• Creating a Database

A new database can be created trough command line or using graphic tools like "MYSQL GUI Tools". The default database is named mhk.

1. On command line log in as user root and enter password you defined on installation. The MySQL client should then display the "mysql>" prompt.

mysql -u root -p

2. Create a new database named mhk

mysql> CREATE DATABASE mhk;

############### The problem here is that the process is too complex. There should be a single parameter necessary. See New_Intalation_Model? for notes how it should be done.svnx

• stop tomcat
• put the mhk.war into the webapps directory of MHK. The MHK webapp is provided as a zip file with a name like MHK2.0-NNN . Unzip the file and you should have a mhk.war file to put into the webapps directory.
• restart tomcat
• locate mhk.properties.

o In windows .... complete o In a Macintosh: If tomcat was installed in the user directory and is being run from the user account the mhk.properties file is at the the root of the home directory /Users/

<user>

/mhk.properties o change to point to your directories.

• restart to tomcat
• create the database in System
• start translating and importing.

Creating a new base is now automatic in MySQL but it stills requires that you go to system prefs and do createdb

install JEDIT follow the manual for the installation of MHK Jedit modules.

4. Troubleshooting