Installing on Apache Tomcat™

Introduction

This document shows you how to install AppThena on the Apache Tomcat™. Apache Tomcat is the reference implementation for Java servlets and JSP.

Please see the general installation instructions for tips and information that apply to other application servers as well as Tomcat.

Tomcat 6.0

Deploying AppThena

You can deploy AppThena by dropping the .war file from the distribution into your $CATALINA_HOME\webapps directory.

Some Tomcat distributions won't unpack the WAR file automatically. In this case you can just unpack it yourself using any programme that can unpack ZIP files (e.g. WinZip™).

If you want to run AppThena as the root application then you must rename the appthena directory to ROOT. You will need to remove or rename Tomcat's default ROOT application first. If you want Tomcat to unpack AppThena then you should rename the .war file.

Configuring the JDBC Database Connection

Put your JDBC driver's JAR file in Tomcat's $CATALINA_HOME\lib directory. If you installed Tomcat on Microsoft Windows and used the default options then the directory will be here:

C:\Program Files\Apache Software Foundation\Tomcat 6.0\lib

Create the $CATALINA_HOME\conf\Catalina\localhost sub-directories if they don't already exist.

Create the context file:

  • Option One: Create a file in $CATALINA_HOME\conf\Catalina\localhost with the same name as the directory that contains your web application and a .xml extension. For example, if your web application is deployed in $CATALINA_HOME\webapps\accounts then the configuration file must be called accounts.xml.
  • Option Two: Create a file in the META-INF directory within your web application directory. For example, $CATALINA_HOME\webapps\accounts\META-INF\context.xml. WARNING This method will not work if you auto-deployed AppThena. i.e. there's a copy of appthena.war in the $CATALINA_HOME\webapps directory. (Last checked with Tomcat 6.14)

Paste the following xml fragment into your context file.

<Context>
  <!-- Configure the database connection. This one uses the Microsoft SQL Server 2005 driver. -->
  <Resource name="jdbc/AppThenaDB"
    type="javax.sql.DataSource" auth="Container"
    maxActive="100" maxIdle="30" maxWait="10000"
    description="Accounts Database"
    driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
    url="jdbc:sqlserver://localhost:1433;DatabaseName=accounts;applicationName='Accounts Database'"
    username="sa" password=""
  />
  <!-- Create an access log for this site -->
  <Valve className="org.apache.catalina.valves.AccessLogValve"
    directory="logs"
    prefix="accounts." suffix=".log"
    pattern="combined"
    resolveHosts="true"/>
  </Context>

Now modify the fragment to configure your JDBC database driver correctly. The values that you need to change are the standard parameters for setting up a JDBC connection. They will be described in the documentation that came with your JDBC driver.

The JDBC parameters that you need to change are:

Parameter Value Examples
driverClassName The java class name for the JDBC driver that you're using. org.apache.derby.jdbc.ClientDriver com.microsoft.jdbc.sqlserver.SQLServerDriver
url The JDBC connection URL for your database. jdbc:derby://localhost:1527/MyDatabase; jdbc:microsoft:sqlserver://localhost:1433;DatabaseName=MyDatabase;
username The name of a database account that has access to this database.
password The password for this database user.

Creating Users

Users are required to log in to use your application. Tomcat allows you to store user names and passwords in various places including a database. However, the default installation assumes that they are kept in $CATALINA_HOME\conf\tomcat-users.xml.

Start by adding a role to the file. The name of the role must match the value of the security-role/role-name element in your web.xml file. The default value is "appthena".

 <role rolename="appthena"/>

Then add as many users as necessary. Add the name of the role to the roles attribute for each user. e.g.

<user username="accountant" password="wizard" roles="appthena"/>
<user username="admin" password="free" roles="admin,manager,appthena"/>

You must restart Tomcat for any changes to take effect.

See the Tomcat documentation for more information if you need to use user names and passwords that are stored in other systems such as databases or LDAP.

Trouble Shooting

Error Code 403 - Access Denied

Your users can log in but see an HTTP error page with the following message:-

 HTTP Status 403 - Access to the requested resource has been denied

In this case, the user's name and password have been set up correctly but the user is not associated with the web application's role. If your users are configured in $CATALINA_HOME\conf\tomcat-users.xml then make sure you've added the role name to the roles attribute.

See above for more information on configuring users.

Error - Failed to create database connection

You can log in but as soon as you try to visit a page that requires database access you see the following error.

 Failed to create database connection.

This error usually means that the JDBC connection is not configured correctly. It may also happen if the database server is not available or is hidden behind a firewall.

Tomcat 5.5

Configuring Tomcat 5.5 is almost exactly the same as configuring Tomcat 6.0. The only difference is that the JDBC driver files go in the $CATALINA_HOME\common\lib directory.

Tomcat 5.0

AppThena is compatible with this version of Tomcat but we do not have any installation instructions at this time.

Tomcat 4.1 and Earlier

These versions are not supported as they do not support the necessary versions of the servlet and JSP specifications. Please use a later version.