Universal Email Access System Installation Instructions

Index

1. What is needed?
2. The deployment process
3. How to set up Tomcat
4. Configuration files
5. Configuring the database
6. Starting, testing and troubleshooting the application

1. What is needed?

To be able to install UEAS, you need a working version of the Java Virtual Machine (at least version 1.3) and one great tool called Ant, version 1.5 at least. You can get Java from http://java.sun.com and Ant from here: http://ant.apache.org.

Top

2. The deployment process

The first thing that needs to be done before deploying the application is compiling it. Once you have installed Ant, unpack the release of UEAS in a temporary folder. You should see the following structure of folders:

deps/
docs/
src/
web/
build.xml
build.properties

The last two files, build.xml and build.properties are used by Ant and specify how the installation should be done (more on this later), the src/ folder contains the sources of the application, the web/ folder contains some additional resources such as the configuration files, the docs/ folder contains documentation such as this document and the deps/ folder contains all the Java libraries needed to compile and run the application.

Before compiling the sources, we need to make sure that we have all the required .jar files needed by the application. You can either get the latest ueas-java-components package from the SourceForge download page (https://sourceforge.net/project/showfiles.php?group_id=73288&release_id=138965) or manually grab the packages one by one, being really careful in choosing the right version (unexpected behaviour can happen if a newer or older version other than the one used for development is used) We recommend that you download the components package if you want to make sure that you have the right versions and packages. Once we have the depencies files, they should be moved to the deps/ folder so that they can be found by the Ant tool when building the application.

After completing all these steps we are ready to run the command that will compile all our source files:

user@host ueas$ ant compile

Ant itself should be able to compile the files choosing the correct CLASSPATH and including in it all the dependencies of the application. Now, and before letting Ant handle the deployment step, we have to modify the file build.properties. Among some other settings, one of the most important is catalina.home and specifies where our Tomcat is installed, so the only thing we need to do is set it to the right path. Something like this (assuming that we installed Tomcat in /opt/jakarta-tomcat-4.0.2!):

catalina.home = /opt/jakarta-tomcat-4.0.2

Other important settings are:

db.host	The host where the MySQL database will be running.
db.username	The username that will be used to connect to the database server.
db.password	The password associated to the user that will be used to connect to the database
db.name	The name of the database that will be used

It is very important that we set these values to the right values, as they will be used to automatically generate the configuration files. They can be changed later on if needed, but the Ant script will make these things easier for us.

Next step is to deploy the application. To do so, we need to issue the following command:

user@host ueas$ ant deploy

And will automatically copy all the necessary java classes, properties files and dependency .jar files to the appropriate folders under the webapps/ folder of our Tomcat installation. We must be careful and check that we set the catalina.home property to the right value and that we have enough permissions to write to that folder.

Top

3. How to set up Tomcat

The file ueas/WEB-INF/web.xml that can be found under the webapps/ folder of your Tomcat setup, defines various properties of the servlet inside the servlet container. One that is automatically defined by the deployment process is the default context path that the servlet will have. By default, the UEAS service can be found in http://host:port/ueas. Please refer to the Tomcat documentation for more information on which settings can be used in the file.

Top

4. Configuration files

This is a list of the configuration files used by the application. The amount of changes required to them has been kept to the minimum and everything is automatically handled by the Ant tool. However, if there is anything that still needs to be changed or tweaked, the following specifies which is the function of every file in the system:

File name	Purpose
config.properties	This file has all sorts of miscellaneous settings of the application, such as enabling or disabling the administration interface, which SMTP server to use, where the locale files can be found and so on. It is better to have a look at it as every setting has a brief but explanatory comment associated to it.
velocity.properties	This file basically tells the Velocity template engine where the different template files can be found within the application tree. It will be automatically configured by the Ant tool, according to the settings we had in the build.properties file, but those settings can be manually changed later on. The default settings should be pretty obvious and should suffice every installation, but the Velocity project documentation will be of invaluable help if any change needs to be made.
log4j.properties	This file controls the Log4j logging system. Generally, it is enough if we use the default values included there, as the deployment step will automatically configure everything for us. The default values define a single log file, in plain ASCII text, which is rotated every day at 00:00. There is an example included in that file on how to have html logging enabled as well. But please be aware that html logging will make the log file immensely huge after just a few hits. You can also have a look at the excellent documentation provided by the log4j project here.
db.properties	This file has the database oriented settings, such as the user, password, host and so on. If we configured the build.properties file correctly, there is no need to change anything in this file.
renderer.properties	This file shouldn't be changed in a default installation unless we have developed some new templates to replace some of the default ones. More on this file and on developing new custom templates can be found in the development-related documentation. As a normal user of the software, there is no need to worry about this file.
terminal.properties	This file controls how terminals are identified by the application. Basically every terminal is detected by trying to match a regular expression on the user-agent and the accept HTTP headers. If both regular expressions evaluate to true, then the terminal will be assigned to that type. Every terminal type specifies, amongst others, which id it will use and the MIME type that has to be sent back to the client. By default it comes with the settings necessary to identify HTML clients (browsers and (x)html-capable devices, WML-enabled devices and VoiceXML gateway servers.

Top

5. Configuring the database

In order to be able to connect to the database, first of all we need a username and a password. Please refer to the MySQL documentation on how to create users and grant them privileges. The user created for the application should have enough privileges to insert and select records. The table creation process does not have to be necessarily handled with the same user that will access the database since no dynamic tables will be created during the normal operation of the application.

After creating a user, we have to run the following command:

user@host ueas$ ant initdb

Once more the Ant script will take care of creating the tables for us, using the settings for the connection defined in the file build.properties

Top

6. Starting, testing and troubleshooting the application
If we have followed all the steps so far, we should be able to start the application. To do so, we can either use the Tomcat manager application or simply restart the whole servlet container. Whichever way, we should be able to connect and see the welcome/login screen if we point our browser to this URL: http://home:port/ueas (where host and port depend on your Tomcat installation)

If we don't see anything, just a blank page, the first thing we should check is the application logs. They can be found in the folder ueas/logs, and they should have enough information to help us track down the possible cause for the malfunctioning.

In the case we don't even get a blank screen but an error message from the servlet container, Tomcat in our case, then we should check the log files generated by Tomcat. They can be found under jakarta-tomcat-x.y.z/logs and usually are self-explanatory. You can refer to the Tomcat documentation for more information.

Top

Contact