Installation Instructions for All Application Servers

Introduction

This document tells you how to install AppThena on any Java web application server such as Apache Tomcat™, BEA Weblogic™, JBoss™ or IBM Websphere™.

The exact installation method varies from server to server and there are more detailed instructions for the following servers:

Pre-Requisites

You must have installed the following items before you attempt to install and test AppThena.

  • Java runtime version 5 or later
  • an application server supporting servlet 2.4 and JSP 2.0
  • a JDBC driver for your database supporting JDBC version 3 or later

Please ensure that the Java runtime that you install meets the minimum requirements of both the application server and the JDBC driver.

AppThena requires access to a relational database engine. You can use virtually any product as long as it supports the bulk of ANSI SQL 92 "entry level" standard. The database server does not need to be installed on the same computer as the application server.

Overview

Once you've installed the pre-requisites you need to complete the following steps:

  • deploy the AppThena WAR file
  • configure the database connection
  • configure the users

You must go through these steps once for each AppThena web application that you wish to host on the application server. The different applications should not affect one another provided that they have different servlet contexts and use different database connections. In fact, you should be able to deploy different versions of AppThena on the same server.

Please ensure that each web application is covered by a valid runtime licence. Free licences are available for development and testing.

Deploying the WAR File

Please consult your application server's documentation for exact information on deploying an application as a WAR file.

Many application servers create a servlet context with the same name as the WAR file. For example, if the WAR file is called appthena.war then the servlet context would be "/appthena" and the url to access the application would be of the format http://localhost/appthena/.

In many cases, you will be able to rename the servlet context after you've deployed the WAR file. However, it maybe be easier to rename the WAR file before deployment.

Please consult your application server's documentation if you want to run the web application as the root application. This means that the application's url would be http://localhost/ instead of http://localhost/appthena/.

Please ensure that the servlet context that you choose is compatible with your runtime licence. Some licences are valid only with certain context names.

Configuring the Database Connection

AppThena requires the application server to provide the application with a JDBC DataSource. (Essentially, a pool of database connections.)

Please consult your application server's documentation for instructions on creating a DataSource.

The JNDI name of the DataSource must match the reference to it in the application's web.xml file. See the resource-ref/res-ref-name element. The web.xml file is contained in your deployment's WEB-INF directory.

If you install more than one AppThena application in the same application server then the DataSource for each application must have a different JNDI name.

Creating Users

AppThena applications require users to login.

If you want anyone to be able to use your application without logging in then you should disable the security constraint in the WEB-INF/web.xml file: just delete or comment out the security-constraint element with the display-name "All Resources Security Constraint".

If you wish to keep the login facility then you must configure your application server so that it knows who is entitled to use the application. Please see your server's documentation for information on configuring users.

Please note that the role-name element in the security-constraint must be different for each group of users. If you have installed several AppThena applications then any user authorized to access one of them will be able to access all of the applications unless you use a different role-name for each application.