Skip to end of metadata
Go to start of metadata

Instructions for installing, deploying, configuring Archiva for the Apache Tomcat web container.


Basics & Fundamentals

With every Tomcat version you will need a few things before you can deploy Archiva.

  1. Use at least Java JDK 1.5.0_11 to run Tomcat w/Archiva.
  2. A defined <Context> xml section to define the JNDI resources.
  3. The Javamail / Activation JAR files.
  4. The Apache Derby JAR files.
  5. Configure ${appserver.base} java property.

Archiva Configuration

Archiva is configured using the ~/.m2/archiva.xml configuration file by default when using a Java EE application server.

Defining JNDI Resources.

Archiva will, on startup, ask the web container for a few JNDI configured resources, two jdbc datasources, and one javamail session.

To configure these JNDI resources in the Tomcat Web Container, you will need to specify a <Context> section that Tomcat can utilize for those requests coming from Archiva.

Tomcat has 3 main ways to accomplish this (ordered by most recommended to least recommended)

  1. Creating a $CATALINA_HOME/webapps/archiva/META-INF/context.xml containing a <Context> element.
  2. Creating a $CATALINA_HOME/conf/Catalina/localhost/archiva.xml containing a <Context> element.
  3. Adding a <Context> Section into the $CATALINA_HOME/conf/server.xml

The following are the JNDI names you will need to provide.

  • mail/Session
  • jdbc/archiva
  • jdbc/users

The individual techniques for describing these resources, and the parameters associated with them are specific to the Tomcat version, resource type, and even jdbc implementation type.

For the purposes of this document, the following assumptions are made.

  1. You are an Apache Tomcat administrator.
  2. You have an SMTP Server on localhost, port 25, with no login / password.
  3. You will be using the embedded Apache Derby database. (not an external database, that's another show)
  4. Details specific to Apache Tomcat, Javamail, or Apache Derby are left for the reader to research on those projects websites.

The Javamail / Activation JAR files

Archiva requires Javamail 1.4 (or later)

Apache Tomcat does not typically ship with a copy of the Javamail or Activation jar files. In your role as the Apache Tomcat administrator of your installation, you will need to obtain these jar files and place it into your preferred lib directory.

The appropriate lib directory to choose is a personal preference, and we do not encourage or enforce a specific location for it, as all installations of Apache Tomcat are different.

For the record, we personally put them in the $CATALINA_HOME/common/lib/ directory.

Direct download links for these jar files.

The Apache Derby JAR files

Archiva 1.0 has been tested with Apache Derby

Default installation of Archiva utilizes the Apache Derby 100% Java Database to maintain Archiva specific information, and also the Users / Security Database.

You will need to obtain the derby.jar and derbytools.jar and place them into your preferred lib directory.

We put them into the $CATALINA_HOME/common/lib/ directory.

Direct download links for these jar files.

Configure the appserver.base java property

The ${appserver.base} java property is used by the Archiva internal logging configuration to determine where to output its logs to. It is important to define this property either in the $CATALINA_OPTS system environment variable (if Tomcat is being launched via the command line) or the service properties (if being launched as a service or daemon).

The format typically expected is -Dappserver.base=<SOMEWHERE>

You can utilize the $CATALINA_HOME/bin/ script to set this value in a tomcat specific way.

Early versions of Archiva 1.0-SNAPSHOT have a bug (described in MRM-288) that prevents startup if a ${appserver.base}/conf/archiva.xml is not present.

If you think you have this issue, create that file and put the following contents into it.

When running tomcat as a windows service, the ${appserver.home} and ${appserver.base} properties must be set using regedit (see installation instructions). Please note, when running the tomcat service on a 64-bit Windows 7 machine, you can find the procrun node under wow6432.

Tomcat 5.0.x Specifics

Tested on Tomcat v5.0.28

These instructions explain how to deploy the (unreleased) Archiva 1.0-SNAPSHOT web application in an existing installation of Tomcat 5.0.x.

Extra Jars:

  • You will need the xalan-2.7.0.jar copied into your $CATALINA_HOME/common/lib/ directory.
  • The Xerces XML Implementation provided in Tomcat 5.0.x is old and will cause problems with Archiva and the internal JAXP implementation in JDK 1.5, we recommend that you remove the files in $CATALINA_HOME/common/endorsed/.

Tomcat 5.5.x Specifics

Tested on Tomcat v5.5.17 and v5.5.25

This example <Context> assumes technique #2 in the Define JNDI Resource list. (This example lists out the docBase to the war file itself.)


The Tomcat 5.5.20 and 5.5.23 releases are missing MailSessionFactory and a few other classes. JNDI mail sessions will not work. Use Tomcat 5.5.17 or see the workaround on Bug 40668.

Tomcat 6.0.x Specifics

Tested on Tomcat v6.0.14

  • No labels