This page last changed on Feb 17, 2011 by smaddox.

While the individual server install guides provide specific instructions, it is useful to have an overall conceptual overview of what the configuration process involves.

Webapp layout

After downloading and unpackaging the JIRA webapp, one is presented with a directory containing:

appendcp.bat
build.bat
build.sh
build.xml
edit-webapp
etc
licenses
readme.txt
src
tools
updater
webapp

The build.xml file is an Ant file, which when invoked with the build.(sh|bat) script, will construct a deployable webapp. build.xml does this by copying the contents of the webapp/ directory, and overwriting it with the contents of edit-webapp/. Thus, never edit files in the webapp/ directory! If a file needs editing, first copy it from webapp/path/to/file to edit-webapp/path/to/file, and edit it there.

Database configuration

The biggest part of configuring JIRA is connecting it up to a database. In J2EE apps like JIRA, the server (Tomcat, Orion etc) is responsible for setting up a Database connection factory, and then makes this available to the webapp (JIRA) via a lookup API called JNDI. So all the hard work, setting up JDBC URLs, usernames and passwords, is done in the app server. All JIRA needs is the JNDI address where it can find the database connection, in the form of a java.sql.DataSource object.

Beyond just getting a database connection, JIRA also needs to know what type of database it is dealing with, so it can issue appropriate SQL commands.

Transaction Manager configuration

J2EE apps also rely on a Transaction Manager to coordinate updates across multiple databases. While JIRA does not currently use this facility, JIRA's underlying library (OfBiz) still requires a transaction manager object. As with database connections, this is provided by the application server, as a javax.transaction.UserTransaction object looked up via JNDI.

User management configuration

JIRA stores all user profiles in a database table. Occasionally, integration with external user management systems like LDAP is required. This requires some configuration of osuser.xml. See The LDAP Integration guide for more information.

So to recap, JIRA needs to know at least three things:

  • The JNDI address of its database connection (a java.sql.DataSource object).
  • What type of database it is dealing with.
  • The JNDI address of a Transaction Manager (a javax.transaction.UserTransaction object).

This is all done in the entityengine.xml file, as described in the database configuration guide. You'll find a copy of entityengine.xml is edit-webapp/WEB-INF/classes, ready to be edited.

There are a few app servers which, for various reasons, we have been unable to use the normal JNDI lookup procedure to obtain a datasource/transaction manager. See the individual app server guides for more details on how these are configured - it generally means that more configuration details end up in entityengine.xml.

Document generated by Confluence on Mar 27, 2011 18:38