While the individual server install guides provide specific instructions, it is useful to have an overall conceptual overview of what the configuration process involves.
After downloading and unpackaging the JIRA webapp, one is presented with a directory containing:
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
edit-webapp/path/to/file, and edit it there.
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
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