EQUIP2 WebApp: Deploying

Chris Greenhalgh, 2007-01-29; last update 2007-10-25

Introduction

This document gives information about deploying an EQUIP2-based Web application. Specific information is given for using Apache Tomcat and Jetty as the the target J2EE Servlet container, but others should also work (as long as they support Servlet 2.4 specification).

Before deployment, the web application must be configured and built: see EQUIP2_WebApp_Configuring_and_Building.html.

Installing the Servlet container

Tomcat

You will require at least Tomcat version 5.5, e.g. Tomcat 5.5.16. Tomcat is commonly used for production services, often behind an Apache web server. 

Tomcat is normally a standalone installation, which runs continually in the background as a service (Windows) or daemon (*nix). See Tomcat's own documentation.

Jetty

Jetty is a pure Java Servlet container which can be run as a service but is more often used as a standalone or embedded container. Current version is (was) 6.1.6, available from http://dist.codehaus.org/jetty/ (rather than the old sourceforge project). By default, run Jetty from a command console in its top-level directory using:
> java -jar start.jar

Running the start.jar directly may have  the same result (although the console may not be visible).

Note: I am currently unsure if behaviour under Jetty differs in key ways from Tomcat.

Other containers

Consule the container's own documentation for installation guidance.

Deploying

Database

If you are using the default HSQLDB in-process database then you don't need to do anything to set up the database.

NOTE: there was an  issue with the previous IDAllocator, which relied on functions and did not work with HSQLDB. The latest IDAllocator should correctly fall back to operating without function(s).

Otherwise, you will need to create the application's back-end database before deploying the application. The details must match the configuration provided in etc/hibernate.cfg.xml. For example, if you are using mySQL (and have changed the Hibernate configuration accordingly) for the default database name/user name/password for the minimal application you can use the mySQL console client to do:

> create database equip2minimal character set utf8 collate utf8_bin;
> grant all on equip2minimal.* to equip2minimal@localhost identified by 'equip2minimalpw';
> flush privileges;

You will require suitable database access rights to do this.

Web application

Deploying an EQUIP2 web application is basically the same as deploying any other Java Servlet-based application.

The web build/deploy process is supported by the following ant build targets:

See below for Checking

If you make changes then doing "ant deploy" again should copy only the changed files into the target container. In some cases these will be picked up right away (e.g. new HTML or JSP files, probably new but not changed java class files and new additional libraries). 

Updating on Tomcat

However in some cases you will need to at least reload the application (use the Tomcat manager), e.g. if you change the web.xml or Spring configuration files.

If you do not have direct access to the Tomcat directory, or if you make a major change and reloading doesn't seem to work then you will need to undeploy the old version (in the Tomcat manager) before deploying the new version (as above).

If undeploy fails then you may need to stop tomcat, delete the web application directory from Tomcat's webapps directory, and restart tomcat.

If deploy fails then you will need to check the Tomcat logs, normally under .../Tomcat 5.5/logs, in particular localhost.<DATE>.log (and any other recently modified files). On windows you may need to open them with notepad rather than wordpad if Tomcat is still running because of file locking issues.

After 10 or so re-deploys/reloads I tend to get an out of memory error ("PermGen"); this seems to be a known issue and requires a restart of Tomcat.

Updating on Jetty

For general changes terminate Jetty (e.g. CTRL-C in its console window) and restart it.

Checking

Deployment

Tomcat

Open a web-browser to view the Tomcat manager page, http://localhost:8080/manager/html (assuming it is running on the local host and port 8080; you will need the Tomcat admin username and password to access this page). This shows a list of deployed web applications and their status.
You should be good to go!

Jetty

Open a web-browser to view the Jetty top-level page, http://localhost:8080/. Although it returns a 404 error it should list the known application contexts, including the newly deployed equip2minimalwebapp/. 

Assuming it does, click through to the web application itself, http://localhost:8080/equip2minimalwebapp/. You should see the index page of your web application. If not: try restarting Tomcat; See Trouble shooting, below.

Trouble Shooting

Common problems include:

Tomcat

Depending on how the application has gone wrong and when, relevant log information may be:

Jetty

Relevant output should be on the console (on windows increase the buffer size for the console window). Check the jetty configuration (by default etc/jetty.xml) for configuration of other logging output(s). This may include:

Changes

2007-10-25
2007-10-24
2007-01-29