JIRA WAR Configuration Overview

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 extracting the JIRA WAR web application archive, your are presented with a directory containing:

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

Directories are indicated by an appending slash symbol.

Please be aware: The build.xml file is an Ant file, which when invoked with the build.sh / build.bat script, will construct deployable web application archive (.war) files (for supported application servers). The build.xml file copies the contents of the webapp subdirectory of your JIRA Installation Directory and overwrites it with the contents of the sibling edit-webapp directory, when constructing its .war files. Thus, unless otherwise requested, never edit files within this webapp directory!
If a file needs editing, first copy it from webapp/path/to/file to edit-webapp/path/to/file subdirectories of your JIRA Installation Directory and edit it in the latter location.

Database Configuration

If you are setting up a new installation of JIRA WAR, the JIRA setup wizard will configure a direct JDBC connection to a new JIRA database. Upon completing the setup wizard, your database configuration will be defined and saved into a dbconfig.xml file located at the root of your JIRA Home Directory.

If you are upgrading JIRA WAR, please ensure a dbconfig.xml file (defining your appropriate database configuration) has been created at the root of your JIRA Home Directory before your new JIRA WAR installation is started. This is ensured if you follow the appropriate manual or migration procedures for upgrading JIRA. For specific database configuration details, refer to the appropriate Configure the database connection manually sections of the specific database connection instructions in the Connecting JIRA to a Database section of this documentation.

Transaction Manager configuration

J2EE-based applications also rely on a Transaction Manager to coordinate updates across multiple databases. While JIRA currently does not 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, which is looked up via JNDI.

Summing Up Database Configuration for JIRA WAR

Hence, JIRA needs to know at least three things:

1. What type of database JIRA is dealing with.
2. The JNDI address of a Transaction Manager (a javax.transaction.UserTransaction object).
3. You database connection details.

Points 1 and 2 are configured in the entityengine.xml file, as described in Configuring the Entity Engine for JIRA. An editable copy of the entityengine.xml file is located in edit-webapp/WEB-INF/classes.

Point 3 is configured in the dbconfig.xml file. The content of this file is generated after completing the JIRA setup wizard.

User management configuration

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