JIRA WAR/EAR Configuration Overview
| 
PDF |
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/
readme.txt
tools/
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.
