JIRA Essentials

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 first glance. For this reason, we have summarized a high-level overview that highlights the most important components in the architecture, as shown in the following figure:

The JIRA installation directory is where you install JIRA. It contains all the executable and configuration files of the application. JIRA neither modifies the contents of the files in this directory during runtime, nor does it store any data files inside the directory; 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 and configuration files that are specific to each JIRA instance, such as JIRA's database connectivity details. As we will see later in this chapter, setting the path to this directory is part of the installation process.

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.

The JIRA_HOME directory can be created anywhere on your system, or even on a shared drive. It is recommended to use a fast disk drive with low network latency to get the best performance from JIRA.

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, as shown in the following table:

When JIRA is running, the JIRA_HOME directory is locked. When JIRA shuts down, it is 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. During shutdown, this file will be removed. However, sometimes JIRA may fail to remove this file, such as during an ungraceful shutdown. In this case, 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 any server that has a 1.5 GHz processor and 1 GB to 2 GB of RAM. As your JIRA usage grows, a typical server will have a quad core 2 GHz CPU and 4 GB of RAM dedicated to the JIRA application.

For production deployment, as in 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. 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.

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. If you are planning to deploy a large instance, it is recommended that you use a 64-bit system.

JIRA has four requirements when it comes to software. It needs a supported operating system and a Java environment. It also 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 requirements and the options that you have to install and run JIRA with.

Since we will be using the installer package with Java bundled, you can skip this section. If you are using the ZIP archive or WAR distribution, you need to make sure you have Java installed on your system.

JIRA 6 requires Java Runtime Environment (JRE) version 7 or a newer run. You can verify the version of Java you have by running the following command in a Command Prompt:

java -version

The preceding command tells us which version of Java is running on your system as shown in the following screenshot:

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 to set up your Java environment:

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

This will display the version of Java installed if everything is done correctly. In Windows, you have to start a new command prompt after you have added the environment variable to see the change.

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:

Now that you have MySQL installed, you need to first create a user for JIRA to connect MySQL with, and then create a fresh database for JIRA to store all its data:

With the Java environment and database prepared, you can now move on to installing JIRA. Normally, there are only two steps:

The JIRA setup wizard

JIRA comes with an easy-to-use setup wizard that will walk you through the installation and configuration process in six simple steps. You will be able to configure the database connections, default language, and much more. You can access the wizard by opening http://localhost:<port number> in your browser, where the <port number> is the number you have assigned to JIRA in step 6 of the installation.

In the first step of the wizard, you will be asked to select Server Language and what database JIRA should connect to.

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 the Built In option, JIRA will use its bundled in-memory database, which is good for evaluation purposes. If you want to use a proper database, such as in our case, you should select the My Own Database option.

Note

The Built In option is great to get JIRA up and running quickly for evaluation purposes.

After you have selected the My Own Database option, the wizard will expand for you to provide the database connection details. If you do not have the necessary database driver installed, JIRA will prompt you for it, as shown in the preceding screenshot.

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. You should be able to move onto the next step by clicking the Next button. 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. 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 need to select whether you want to install only JIRA, or if you would like to install additional add-ons. In this example, we will be installing JIRA only, so select the I'm using JIRA for project tracking option and click on Next. You can install these additional add-ons later.

In the fourth step, we need to provide a license key for JIRA. If you have already obtained a license from Atlassian, you can select I have a JIRA key option. Then cut and paste it into the License Key text box. If you do not have a license, you can generate an evaluation license by selecting either I have an account but no key option if you have an account on https://my.atlassian.com, or by selecting I don't have an account to register a new account with Atlassian. Evaluation license will grant you access to JIRA's full set of features for one month.

In the fifth 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 Chapter 10, JIRA Service Desk. Fill in the administrator account details and click on Next to move on to the last step.

Note

This account is important and it can help you troubleshoot and fix problems later on. Do not lose it!

In the sixth 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. 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, you can skip this step now by selecting the Later option and clicking on Finish. You can configure your e-mail server settings later, as you will see in Chapter 7, E-mails and Notifications.

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

Starting and stopping JIRA

Since JIRA is installed as a Windows service, you can start, stop, and restart it via the Windows services console, by navigating to Start | Control Panel | Administrative Tools | Services. In the services console, look for Atlassian JIRA, and you will be able to stop and start the application, as shown in the following screenshot:

The default memory setting for JIRA is usually sufficient for a small-to medium-sized deployment. As JIRA's adoption rate increases, you will find that the amount of memory allocated by default is no longer enough. If JIRA is running as a Windows service we described in this chapter, you can increase the memory as follows:

If you are not running JIRA as a Windows service, you need to open the setenv.bat file (for Windows) or the setenv.sh (for Linux) file in the JIRA_INSTALL/bin directory. Then, locate the following lines:

set JVM_MINIMUM_MEMORY="384m"
set JVM_MAXIMUM_MEMORY="768m"

Change the value for the two parameters and restart JIRA. Normally, 4 GB (4096m) of memory is enough to support a fairly large instance of JIRA used by hundreds of users.

As a part of the installation process, the installation wizard prompted us which port JIRA should listen for incoming connections. If you have accepted the default value, it is port 8080. You can change the port setting by locating and opening the server.xml file in a text editor in the JIRA_INSTALL/conf directory. Let's examine the relevant contents of this file:

<Server port="8005" shutdown="SHUTDOWN">

This line specifies the port for command to shutdown JIRA/Tomcat. By default, it is port 8005. If you already have an application that is running on that port (usually another Tomcat instance), you need to change this to a different port:

<Connector port="8080" protocol="HTTP/1.1">

This line specifies which port JIRA/Tomcat will be running on. By default, it is port 8080. If you already have an application that is running on that port, or if the port is unavailable for some reason, you need to change it to another available port:

<Context path="/jira" docBase="${catalina.home}/atlassian-jira"  reloadable="false" useHttpOnly="true">

This line allows you to specify the context that JIRA will be running under. By default, the value is empty, which means JIRA will be accessible from http://hostname:portnumber. If you decide to specify a context, the URL will be http://hostname:portnumber/context. In our example here, JIRA will be accessible from http://localhost:8080/jira.

By default, JIRA runs with a 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 obtained from a certification authority, such as VeriSign (CA certificate), or a self-signed certificate generated by you. A CA certificate will not only encrypt data for you, but also identify your copy of JIRA to the 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 JIRA_HOME\jre\bin directory if you are using the installer package. If you are using your own Java installation, then you can find it in JAVA_HOME\bin.

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  JIRA_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. Then, 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.