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.
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.
build.xmlfile is an Ant file, which when invoked with the
build.batscript, will construct deployable web application archive (
.war) files (for supported application servers). The
build.xmlfile copies the contents of the
webappsubdirectory of your JIRA Installation Directory and overwrites it with the contents of the sibling
edit-webappdirectory, when constructing its
.warfiles. Thus, unless otherwise requested, never edit files within this
If a file needs editing, first copy it from
edit-webapp/path/to/filesubdirectories of your JIRA Installation Directory and edit it in the latter location.
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:
- What type of database JIRA is dealing with.
- The JNDI address of a Transaction Manager (a javax.transaction.UserTransaction object).
- 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
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.