JIRA 5.2 Essentials: Learn how to track bugs and issues, and manage your software development projects with JIRA, Second Edition

Atlassian provides a comprehensive overview of the JIRA architecture at https://developer.atlassian.com/display/JIRADEV/JIRA+Architectural+Overview. However, for day-to-day administration and usage of JIRA, we do not need to go into details; the information provided can be overwhelming at the first glance. For this reason, we have summarized a high-level overview that highlights the most important components in the architecture:

The JIRA installation directory is where you install JIRA. It contains all the executable and configuration files of the application. JIRA does not modify the contents of the files in this directory during runtime, nor does it store any data inside; the directory is used primarily for execution. For the remainder of the book, we will be referring to this directory as JIRA_INSTALL.

The JIRA home directory contains key data files that are specific to each JIRA instance. There is a one-to-one relationship between JIRA and this directory. This means each JIRA instance must and can have only one home directory, and each directory can serve only one JIRA instance. In the old days, this directory was sometimes called the data directory. It has now been standardized as the JIRA Home. It is for this reason that for the rest of the book we will be referring to this directory as JIRA_HOME.

It is recommended that JIRA_HOME be created separately from JIRA installation. This separation of data and application makes tasks, such as maintenance and future upgrades, an easier process.

Within JIRA_HOME, there are several subdirectories that contain vital data:

When JIRA runs, this directory gets locked, when JIRA shuts down, it gets unlocked. This locking mechanism prevents multiple JIRA instances from reading/writing to the same JIRA_HOME directory and causing data corruption.

JIRA locks the JIRA_HOME directory by writing a temporary file called jira-home.lock into the root of the directory, and during shutdown, it will be removed. However, sometimes JIRA may fail to remove this file, such as during an ungraceful shutdown. In these cases, you can manually remove this locked file to unlock the directory, so that you can start up JIRA again.

For evaluation purposes, where there will only be a small number of users, JIRA will run happily on a normal workstation computer that has a 1.5 GHz processor and 256 MB to 512 MB of RAM. As a matter of fact, many organizations start their JIRA from a simple desktop and eventually migrate onto a proper server hardware.

For production deployment, as most applications, it is recommended that you run JIRA on its own dedicated server. There are many factors that you should consider when deciding how much resource to allocate to JIRA, and also keep in mind how JIRA will scale and grow. When deciding on your hardware needs, you should consider the following:

It can be difficult at times to estimate these figures, so as a reference, a server running with 2.0+ GHz of dual/quad CPU and 1 GB of RAM will be sufficient for most instances with around 200 users. Starting with JIRA 5.1, JIRA has significantly improved its performance and scalability, especially for large deployments. It is now able to handle more than 250 thousand issues with ease.

Officially, JIRA only supports x86 hardware and 64 bit derivatives of it. When running JIRA on a 64 bit system, you will be able to allocate more than 4 Gb of memory to JIRA, a limit if you are using a 32 bit system. So, if you are planning to deploy a large instance, it is recommended that you use 64 bit.

JIRA has four requirements when it comes to software. It needs to run on top of an operating system, and a Java environment. It needs an application server to host and serve its contents, and a database to store all of its data. In the following sections, we will discuss each of these components and the options that you have to install and run JIRA with.

JIRA 5 requires Java Runtime Environment (JRE) version 6 update 18 or higher to run. If you already have a JDK installed, then you can skip this section. If you are not sure, then you can verify this by running the following command in a command prompt:

java -version

If you do not see a similar output, then chances are, you do not have Java installed. You will need to perform the following steps below to set up your Java environment.

To install JDK onto your system, simply perform the following steps:

The next step is to prepare an enterprise database for your JIRA installation. JIRA requires a fresh database. If during the installation process, JIRA detects that the target database already contains any data, it will not proceed. If you already have a database system installed, then you may skip this section.

To install MySQL, simply perform the following steps:

With the Java environment and database prepared, you can now move on to install JIRA. Normally, there are only two steps—create and set up the JIRA_HOME directory and run through the JIRA setup wizard.

JIRA 5 comes with an easy-to-use setup wizard that will walk you through the installation and configuration process in four simple steps. You will be able to configure database connections, default language, and much more.

Once you complete the preceding steps, you can start up JIRA by running the start-jira.bat file from the JIRA_INSTALL\bin directory. You will see a command prompt opening up and eventually an output similar to the following screenshot, ending with INFO: Server startup in x ms:

If you see the output similar to the preceding screenshot, it means that your JIRA is up and running. Now, you can fire up your browser and point it to http://localhost:8080 to start the setup wizard.

In the first step of the wizard, you will be asked to select Server Language and whether JIRA should use an internal or External Database connection.

The server language will determine what language will be used when users access JIRA. You will see that as soon as you make a change from the drop-down list, JIRA will automatically change its onscreen text to the selected language.

The database connection setting will determine what database JIRA will use. If you select Internal, JIRA will use its bundled in-memory database, which is great for evaluation purposes. If you want to use a proper enterprise database, such as in our case, you should select the External option.

After you have selected the External option, the wizard will expand for you to provide the database connection details. Once you have filled in the details for your database, it is a good idea to first click on the Test Connection button to verify that JIRA is able to connect to the database. If everything is set up correctly, JIRA will report back with a success message, and you should be able to move onto the next step by clicking on Next. This may take a few minutes, as JIRA will now create all the necessary database objects. Once this is done, you will be taken to step 2 of the wizard.

In the second step, you will need to provide some basic details about this JIRA instance, and most importantly, the license key. If you have already obtained a license from Atlassian, you can cut and paste it into the License Key text box. If you do not have a license, you can generate an evaluation license by clicking on the Generate an Evaluation Key link at the bottom. An evaluation license allows you to use JIRA with its full features for three months. Once you have filled in the required properties, click on Next to move on to step 3 of the wizard:

In the third step, you will be setting up the administrator account for JIRA. It is important that you keep the account details somewhere safe and do not lose the password. Since JIRA only stores the hashed value of the password instead of the actual password itself, you will not be able to retrieve it. However, there are methods for you to reset the password if you do lose it, as we will see in the later chapters. Fill in the administrator account details and click on Next to move on to the last step:

In the fourth and final step, you can set up your e-mail server details. JIRA will use the information configured here to send out notification e-mails. As you will see in Chapter 7, E-mails and Notifications, notification is a very powerful feature in JIRA and one of the primary methods for JIRA to communicate with the users. If you do not have your e-mail server information handy, do not worry, you can skip this step now by clicking on Disable Email Notifications. JIRA allows you to change your e-mail server settings anytime; we will cover the settings in Chapter 7, E-mails and Notifications, when we delve deeper into JIRA's notification system. After you have filled in the e-mail server details, click on Finish to complete the setup wizard:

Congratulations! You have successfully completed your JIRA setup, and you will be taken directly to your new JIRA instance, with a welcome message.

Your JIRA is now installed and running, however, at the moment, if you restart your server, you will need to manually start up JIRA. In a production environment, it is usually required for applications to start up automatically when the system reboots, in events such as hardware upgrades and system patching. In Windows, this means you need to install JIRA as a service.

To configure JIRA as a Windows service, simply follow the steps below:

You can now start/stop/restart JIRA from the Windows services panel. You can also set JIRA to start automatically.

In both standalone and WAR distributions, you can configure some of the applications server settings, such as context path and port number. This is useful, for example, if you have multiple servers running on the same machine, then they can co-exist by listening on different port numbers. If JIRA is the only application running on your machine, then you may choose not to make any changes. Another reason you might want to change the port number to a standard port such as 80 instead of 8080, is so that you will not need to type in the port number as a part of the URL.

To configure the settings, locate and open the server.xml file in a text editor. The file can be found in the JIRA_INSTALL/conf directory:

<Server port="8005" shutdown="SHUTDOWN">
… … … …
<Connector port="8080" protocol="HTTP/1.1">
… … … …
<Context path="/jira" docBase="${catalina.home}/atlassian-jira" reloadable="false" useHttpOnly="true">

Let's examine the relevant contents in this file:

By default, JIRA runs with standard, non-encrypted HTTP protocol. This is acceptable if you are running JIRA in a secured environment, such as an internal network. However, if you plan to open up access to JIRA over the Internet, you will need to tighten up security by encrypting sensitive data, such as usernames and passwords that are being sent, by enabling HTTPS (HTTP over SSL).

For a standalone installation, you will need to perform the following tasks:

First, you need to get a digital certificate. This can be from a certification authority such as VeriSign (CA certificate), or a self-signed certificate generated by you. CA certificate will not only encrypt data for you, but also identify your copy of JIRA to users. A self-signed certificate is useful when you do not have a valid CA certificate and you are only interested in setting up HTTPS for encryption. Since a self-signed certificate is not signed by a Certification Authority, it is unable to identify your site to the public, and users will be prompted with a warning that the site is untrusted when they first visit it. However, for evaluation purposes, a self-signed certificate will suffice until you can get a proper CA certificate.

For the purpose of this exercise, we will create a self-signed certificate to illustrate the complete process. If you have a CA certificate, you can skip the following steps.

Java comes with a handy tool for certificate management called keytool , which can be found in the JAVA_HOME\lib directory. To generate a self-signed certificate, run the following commands from a command prompt:

keytool –genkey –alias tomcat –keyalg RSA
keytool –export –alias tomcat –file file.cer

This will create a keystore (if one does not already exist) and export the self-signed certificate (file.cer). When you run the first command, you will be asked to set the password for the keystore and Tomcat. You need to use the same password for both. The default password is changeit. You can specify a different password of your choice, but you then have to let JIRA/Tomcat know, as we will see later.

Now that you have your certificate ready, you need to import it into your trust store for Tomcat to use. Again, you will use the keytool application in Java:

keytool –import –alias tomcat –file file.cer JAVA_HOME\jre\lib\security\cacerts

This will import the certificate into your trust store, which can be used by JIRA/Tomcat to set up HTTPS.

To enable HTTPS on Tomcat, open the server.xml file in a text editor from the JIRA_INSTALL/conf directory. Locate the following configuration snippet:

<Connector port="8443" maxHttpHeaderSize="8192" SSLEnabled="true"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="true"/>

This enables HTTPS for JIRA/Tomcat on port 8443. If you have selected a different password for your keystore, you will have to add the following line to the end of the preceding snippet, before the closing tag:

keystorePass="<password value>" 

The last step is to set up JIRA so that it automatically redirects from a non-HTTP request to an HTTPS request. Find and open the web.xml file in the JIRA_INSTALL/atlassian-jira/WEB-INF directory, and add the following snippet to the end of the file, before the closing </web-app> tag:

<security-constraint>
  <web-resource-collection>
    <web-resource-name>all-except-attachments</web-resource-name>
    <url-pattern>*.js</url-pattern>
    <url-pattern>*.jsp</url-pattern>
    <url-pattern>*.jspa</url-pattern>
    <url-pattern>*.css</url-pattern>
    <url-pattern>/browse/*</url-pattern>
  </web-resource-collection>
  <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  </user-data-constraint>
</security-constraint>

Now, when you access JIRA with a normal HTTP URL, such as http://localhost:8080/jira, you will be automatically redirected to its HTTPS equivalent, https://localhost:8443/jira.

With the standalone distributions, JIRA comes bundled with the necessary database drivers for all the supported database systems. However, if you are using the WAR distribution or if for some reason, the database driver gets corrupted, you will need to manually obtain and install the driver.

To install a database driver, simply perform the following steps:

As we have already seen, the JIRA setup wizard takes care of setting up the database connection for us during the installation process. However, there will be times when you will need to make changes to this. The database name or user credentials may have changed, or there may be a need to use a different database altogether.

When the wizard sets up your database connections, these settings are written to a file called dbconfig.xml in the JIRA_HOME directory. Now, you can edit this file directly in a text editor, or you can use a built-in GUI tool to help you with this.

The tool is called JIRA Configuration Tool , a utility application that comes bundled with JIRA. You can find the application in the JIRA_INSTALL/bin directory called config.bat. Double-click on the file to start the application.

Click on the Database tab once the application starts up. You will see that all the configuration options are populated with the settings you just configured:

To verify that your settings are correct, make sure that the database is running and click on the Test Connection button. If everything is correct, you should see a confirmation message as shown in the preceding screenshot. From now on, you can use this utility application to update database configurations for JIRA, and you will know what files are being touched when changes occur.