Jira 8 Essentials - Fifth Edition

4.8 (4 reviews total)
By Patrick Li
  • Instant online access to over 8,000+ books and videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Getting Started with Jira

About this book

Atlassian Jira enables effective bug tracking for your software and mobile applications and provides tools to track and manage tasks for your projects. Jira Essentials is a comprehensive guide, now updated to Jira 8 to include enhanced features such as updates to Scrum and Kanban UI, additional search capabilities, and changes to Jira Service Desk.

The book starts by explaining how to plan and set up a new Jira 8 instance from scratch before getting you acquainted with key features such as emails, workflows, business processes, and much more. You'll then understand Jira's data hierarchy and how to design and work with projects.

Since Jira is used for issue management, this book delves into the different issues that can arise in your projects. You’ll explore fields, including custom fields, and learn to use them for more effective data collection. You’ll create new screens from scratch and customize them to suit your requirements. The book also covers workflows and business processes, and guides you in setting up incoming and outgoing mail servers. Toward the end, you’ll study Jira's security model and Jira Service Desk, which allows you to run Jira as a support portal.

By the end of this Jira book, you will be able to implement Jira 8 in your projects with ease.

Publication date:
February 2019
Publisher
Packt
Pages
420
ISBN
9781789802818

 

Chapter 1. Getting Started with Jira

In this chapter, we will start with a high-level view of Jira, going through each of the components that make up the overall application. We will then examine the various deployment options, system requirements for Jira 8, and the platforms/software that are supported. Finally, we will get our hands dirty by installing our very own Jira 8 from scratch with the installation wizard. Finally, we will also cover some post-installation steps, such as setting up SSL to secure our new instance.

By the end of this chapter, you will have learned about the following:

  • The different offerings from the Jira product family
  • The overall architecture of Jira
  • The basic hardware and software requirements to deploy and run Jira
  • Platforms and applications supported by Jira
  • Installing Jira and all of the required software
  • Post-installation configuration options to customize your Jira
 

Jira Core, Jira Software, and Jira Service Desk


Starting with Jira 7, Jira is split into three different products, and the term Jira now refers to the common platform that all these products are built on. The three products that make up the Jira family are as follows:

  • Jira Core: This is similar to the classic Jira (also known as JIRA), with all the field customizations and workflow capabilities. This is perfect for general-purpose task management.
  • Jira Software: This is Jira Core with agile capabilities (previously known as JIRA Agile). This is well-suited for software development teams that want to use agile methodologies, such as Scrum and Kanban.
  • Jira Service Desk: This is Jira Core with service desk capabilities. This is designed for running Jira as a support ticketing system, with a simplified user interface for the end users, and a focus on customer satisfaction with SLA goals.

As you can see, Jira Core is at the heart, providing all the base functionalities, such as user interface customization, workflows, and email notifications, while Jira Software and Jira Service Desk add specialized features on top of it.

In this book, we will mostly focus on Jira Software. However, since Jira Core provides many of the common features, most of the knowledge is also applicable to Jira Core, and features that are only available to Jira Software will be highlighted. For this reason, the term Jira will be used to cover both Jira Core and Jira Software, unless a distinction is required. We will also cover Jira Service Desk in Chapter 11, Jira Service Desk.

 

The Jira architecture


Installing Jira is simple and straightforward. However, it is important for you to understand the components that make up the overall architecture of Jira and the installation options that are available. This will help you make an informed decision and be better prepared for future maintenance and troubleshooting, as well as establishing some common terminologies that are often used by the user community and Atlassian support representatives.

High-level architecture

Atlassian provides a comprehensive overview of the Jira architecture at https://developer.atlassian.com/server/jira/platform/architecture-overview. However, with regards to the day-to-day administration and utilization of Jira, we do not need to go into the details of this; the information provided can be overwhelming at first glance. For this reason, we have summarized a high-level overview, which highlights the most important components in the architecture, as shown in the following diagram:

Web browsers

Jira is a web application, so there is no need for users to install anything on their machines. All they need is a web browser that is compatible with Jira. The following table summarizes the browser requirements for Jira:

Browsers

Compatibility

Internet Explorer

11 and Edge

Mozilla Firefox

Latest stable versions

Safari

Latest stable versions on mac OSX

Google Chrome

Latest stable versions

Mobile

Mobile Safari on iOS only

Mobile Chrome

Application services

The application services layer contains all the functions and services provided by Jira. These services include various business functions, such as workflow and notification, which will be discussed in depth in Chapter 7, Workflow and Business Process, and Chapter 8, Emails and Notifications, respectively. Other services, such as REST/Web Service, provide integration points to other applications, and the OSGi service provides the base add-on framework to extend Jira's functionalities.

Data storage

The data storage layer stores persistent data in several places within Jira. Most business data, such as projects and issues, are stored in a relational database. Content such as uploaded attachments and search indexes are stored in the filesystem in the JIRA_HOME directory, which we will talk about in the next section. The underlying relational database that's used is transparent to users, and you can migrate from one database to another with ease, as referenced at https://confluence.atlassian.com/adminjiraserver/switching-databases-938846867.html.

The Jira installation directory

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 this book, we will refer to this directory as JIRA_INSTALL.

The Jira home directory

The Jira home directory contains key data and configuration files 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 that each Jira instance must 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 remainder of this book, we will refer to this directory as JIRA_HOME.

The JIRA_HOME directory can be created anywhere on your system, or even on a shared drive, but it cannot be a sub-directory of JIRA_INSTALL. 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:

Directory

Description

data

This directory contains data that is not stored in the database, for example, uploaded attachment files.

export

This directory contains the automated backup archives created by Jira. This is different from a manual export executed by a user; manual exports require the user to specify where to store the archive.

import

This directory contains the backups that can be imported. Jira will only load backup files from this directory.

log

This directory contains Jira log files, which are useful for tracking down errors. Some of the key log files include the following:

  • atlassian-jira.log: Information about Jira Software and the Jira Core application
  • atlassian-servicedesk.log: Information about the Jira Service Desk application
  • atlassian-jira-security.log: Information about user sessions, logins, and logouts

plugins

This directory is where installed plugins (also known as add-ons) are stored. Add-ons will be discussed further in later chapters.

caches

This directory contains cache data that Jira uses to improve its performance at runtime. For example, search indexes are stored in this directory.

tmp

This directory contains temporary files created at runtime, such as file uploads.

 

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. Occasionally, however, 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.

Note

You can manually remove the locked file to unlock the JIRA_HOME directory if Jira fails to clean it up during the shutdown.

 

System requirements


Just like any other software application, a set of base requirements needs to be met before you can install and run Jira. Therefore, it is important for you to be familiar with these requirements so that you can plan out your deployment successfully. Note that these requirements are for a behind-the-firewall deployment, also known as the Jira Server or Jira Data Center. The main difference between the two is that Jira Data Center allows for clustering, so you can have additional benefits such as high availability and better scalability. Atlassian also offers a cloud-based alternative called Jira Cloud, available at https://www.atlassian.com/software#cloud-products.

Hardware requirements

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, and at least 10 GB of hard disk space for your database.

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 the extent of the resources to allocate to Jira; keep in mind how Jira will scale and grow. When deciding on your hardware needs, you should consider the following:

  • The number of active (concurrent) users in the system
  • The number of issues and projects in the system
  • The number of configuration items, such as custom fields and workflows
  • The number of concurrent users, especially during peak hours

It can be difficult at times to estimate these figures. As a reference, a server running with over 2.0 quad core CPU and 4 GB of RAM will be sufficient for most instances with around 200 active users. If you start to get into thousands of active users, you will need to have at least 8 GB of RAM allocated to Jira (JVM). Once you have gone beyond a million of issues and thousands of active users for a single Jira instance, simply adding raw system resources (vertical scaling) will start yield diminishing returns. In such cases, it is often better to consider using the data center edition of Jira, which offers better scalability by allowing you to have multiple instances clustered together (horizontal scaling), with the added benefit of providing high availability.

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, which is the 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.

Software requirements

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. You can find the latest information online at https://confluence.atlassian.com/adminjiraserver/supported-platforms-938846830.html.

Operating systems

Jira supports most of the major operating systems, so the choice of which operating system to run Jira on becomes a matter of expertise, comfort, and, in most cases, the existing organization's IT infrastructure and requirements.

The operating systems supported by Atlassian are Windows and Linux. There is a Jira distribution for mac OSX, but this is mostly for evaluation purposes only. Cloud-based deployment options are also available for Amazon Web Services (AWS) and Microsoft Azure. However, with these cloud options, there are restrictions for components such as database support.

With both Windows and Linux, Atlassian provides an executable installer wizard package, which bundles all the necessary components to simplify the installation process (only available for standalone distribution). There are minimal differences when it comes to installing, configuring, and maintaining Jira on different operating systems. If you do not have any preferences and would like to keep initial costs down, CentOS Linux is a good choice.

Java platforms

Jira is a Java-based web application, so it needs to have a Java environment installed. This can be a Java Development Kit (JDK) or a Java Runtime Environment (JRE). The executable installer that comes with Windows or Linux contains the necessary files and will install and configure the JRE for you. However, if you want to use archive distributions, you will need to make sure that you have the required Java environment installed and configured.

Jira 8 requires Java 8 (also known as 1.8). If you run Jira on an unsupported Java version, including its patch version, you may run into unexpected errors. The following table shows the supported Java versions for JIRA:

Java platforms

Support status

Oracle JDK/JRE

Java 8 (1.8)

 

With the recent licensing changes made to Oracle JDK by Oracle, efforts are currently underway to add support for OpenJDK. However, at the time of writing, OpenJDK is not officially supported.

Databases

Jira stores all its data in a relational database. While you can run Jira with H2 Database, the in-memory database that comes bundled with Jira, it is prone to data corruption. You should only use this to set up a new instance quickly for evaluation purposes, where no important data will be stored. For this reason, it is important that you use a proper database such as MySQL for production systems.

Most relational databases available on the market today are supported by Jira, and there are no differences when you install and configure Jira. Just like operating systems, your choice of database will come down to your IT staff's expertise, experience, and established corporate IT standards. If you run Windows as your operating system, then you probably want to go with the Microsoft SQL Server. On the other hand, if you run Linux, then you should consider Oracle (if you already have a license), MySQL, or PostgreSQL.

The following table summarizes the databases that are currently supported by Jira. It is worth mentioning that both MySQL and PostgreSQL are open source products, so they are excellent options if you are looking to minimize your initial investments.

Database

Support status

MySQL

MySQL 5.6 and newer. Note that neither MariaDB nor PerconaDB are supported.

This requires the latest JDBC driver.

PostgreSQL

PostgreSQL 9.4 and newer.

This requires the latest PostgreSQL JDBC (9.4) driver.

Microsoft SQL Server

SQL Server 2012 and newer.

This requires the latest Microsoft JDBC (6.2.1) driver.

Oracle

Oracle 12c R1.

This requires the latest Oracle driver.

H2

This is bundled with the standalone distribution, for evaluation purposes only.

 

Take special note of the driver requirement on each database, as some drivers that come bundled with the database vendor or Jira itself (for example, PostgreSQL) are not supported and will need to be replaced with the appropriate versions.

Application servers

Jira 8 officially only supports Apache Tomcat as the application server. While it is possible to deploy Jira into other JEE compliant application servers, you will be doing this at your own risk, and it is not recommended.

The following table shows the versions of Tomcat supported by Jira 8:

Application server

Support status

Apache Tomcat

Tomcat 8.5.32 and newer.

You should not deploy other applications or multiple Jira instances into the same Tomcat server.

 

Installation options


Jira comes in two flavors—an executable installer and a TAR.GZ or ZIP archive. The executable installer provides a wizard-driven interface that will walk you through the entire installation process. It even comes with a Java installer to save you some time. The archive flavor contains everything except for a Java installer, which means you will have to install Java yourself. You will also need to perform some post-installation steps manually, such as configure Jira as a service. However, you do get the advantage of learning what really goes on under the hood.

 

Installing and configuring Jira


Now that you have a good understanding of the overall architecture of Jira, the basic system requirements, and the various installation options, we are ready to deploy our own Jira instances.

In the following exercise, we will be installing and configuring a fresh Jira instance for a small production team. We will perform our installation on a Windows platform with a MySQL database server. If you are planning to use a different platform or database, refer to the vendor documentation on installing the required software for your platform.

In this exercise, you will do the following:

  • Install a fresh instance of Jira Software
  • Connect Jira to a MySQL database

We will continue to use this Jira instance in subsequent chapters and exercises as we build our help desk implementation.

For our deployment, we will use the following:

  • Jira Software server distribution 8
  • MySQL 5.7.13
  • Microsoft Windows 7

Installing Java

Since we will be using the installer package that's bundled with Java, you can skip this section. However, if you are using the archive option, you need to make sure that you have Java installed on your system.

Jira 8 requires JRE version 8 (1.8) to 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. We will start by installing JDK on your system:

Note

At the time of writing, the latest version of Java 8 is JDK 8 Update 192.

  1. Double-click on the downloaded installation file to start the installation wizard.
  2. Select where you would like to install Java, or you can simply accept the default values. The location where you install JDK will be referred to as JAVA_HOME for the remainder of this book.
  1. Create a new environment variable named JAVA_HOME with the value set to the full path of the location where you installed Java. You can do this as follows:

1. Open the System Properties window by holding down your Windows key and pressing the Pause key on your keyboard.

2. Select the Advanced system settings option.

3. Click on the Environment Variable button from the new popup:

  1. Edit the PATH environment variable and append the following to the end of its current value:
        ;%JAVA_HOME%\bin
  1. Test the installation by typing the following command in a new Command Prompt:
java -version

This will display the version of Java installed, provided 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.

Installing MySQL

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 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:

  1. Download MySQL from http://dev.mysql.com/downloads, select MySQL Community Server, and then select the MSI installer for Windows.

Note

At the time of writing, the latest version of MySQL is 5.7.13.

  1. Double-click on the downloaded installation file to start the installation wizard.
  2. Click on Install MySQL Products on the welcome screen.
  3. Read and accept the license agreement and click on the Next button.
  4. Select the Server only option on the next screen. If you are an experienced database administrator, you can choose to customize your installation. Otherwise, just accept the default values for all subsequent screens.
  5. Configure the MySQL root user password. The username will be root. Do not lose this password, as we will be using it in the next section.
  6. Complete the configuration wizard by accepting the default values.

Preparing MySQL for Jira

Now that you have MySQL installed, you need to create a user for Jira to connect MySQL with as you should never use the default root user, and then create a fresh database for Jira to store all its data:

  1. Start the MySQL Command Line Client by navigating to Start | All Programs | MySQL | MySQL Server 5.7 | MySQL 5.7 Command Line Client.
  2. Enter the MySQL root user password you set during installation.
  3. Use the following command to create a database:
create database jiradb character set utf8;
  1. Here, we are creating a database called jiradb. You can name the database anything you like. As you will see later in this chapter, this name will be referenced when you connect JIRA to MySQL. We have also set the database to use utf8 character encoding, as this is a requirement for JIRA. Using the following command, you need to ensure that the database uses the InnoDB storage engine to avoid data corruption:
        grant all on jiradb.* to 'jirauser'@'localhost' 
        identified by 'jirauserpassword';

We are doing several things here. First, we create a user called jirauser and assign the password jirauserpassword to them. You should change the username and password to something else.

We have also granted all the privileges to the user for the jiradb database that we just created so that the user can perform database operations, such as create/drop tables and insert/delete data. If you have named your database something other than jiradb, then make sure that you change the command so that it uses the name of your database.

This allows you to control the fact that only authorized users (specified in the preceding command) are able to access the Jira database to ensure data security and integrity.

  1. To verify your setup, exit the current interactive session by issuing the following command:
quit;
  1. Start a new interactive session with your newly created user:
mysql -u jirauser -p
  1. You will be prompted for a password, which you set up in the preceding command as jirauser.
  1. Use the following command:
show databases;

This will list all the databases that are currently accessible by the logged-in user. You should see jiradb among the list of databases.

  1. Examine the jiradb database by issuing the following commands:
use jiradb;show tables;

The first command connects you to the jiradb database, so all of your subsequent commands will be executed against the correct database.

The second command lists all the tables that exist in the jiradb database. Right now, the list should be empty, since no tables have been created for JIRA; but don't worry, as soon as we connect to Jira, all the tables will automatically be created.

Installing Jira

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

  1. Download and install the Jira application
  2. Run through the Jira setup wizard

Obtaining and installing Jira

The first step is to download the latest stable release of Jira. You can download Atlassian Jira from http://www.atlassian.com/software/jira/download.

The Atlassian website will detect the operating system you are using and automatically suggest an installation package for you to download. If you intend to install Jira on a different operating system from the one you are currently on, make sure that you select the correct operating system package.

As we mentioned earlier, with Windows, there is a Windows installer package and a self-extracting archive package. For the purpose of this exercise, we will use the installer package (Windows 64-bit Installer):

  1. Double-click on the downloaded installation file to start the installation wizard and click on the Next button to continue:

  1. Select the Custom Install (recommended for advanced users) option and click on the Next button to continue. Using the custom installation will let us decide where to install Jira and will also provide numerous configuration options:

  1. Select the directory where Jira will be installed. This will become the JIRA_INSTALL directory. Click on the Next button to continue:

  1. Select where Jira will store its data files, such as attachments and log files. This will become the JIRA_HOME directory. Click on the Next button to continue:
  1. Select where you would like to create shortcuts to the start menu and click on the Next button to continue.
  1. In the Configure TCP Ports step, we need to select the port on which Jira will be listening for incoming connections. By default, Jira will run on port 8080. If 8080 has already been taken by another application, or if you want Jira to run on a different port such as port 80, select the Set custom value for HTTP and Control ports option and specify the port numbers you want to use. Click on the Next button to continue:

  1. Select whether you would like Jira to run as a service. If you enable this option, Jira will be installed as a system service and can be configured to start automatically with the server; refer to the Starting and stopping Jira section for more details:
  1. For the final step, review all the installation options and click on the Install button to start the installation:
  1. Once the installation is complete, check the Launch Jira Software in browser option and click on Finish. This will close the installation wizard and open up your web browser to access Jira. This might take a few minutes to load as Jira starts up for the first time:

Installing MySQL driver

Jira 8 comes bundled with the MySQL database driver, so you can skip this section. However, if you do need to manually install the driver for some reason, such as the driver file got corrupted or accidentally deleted, you can download the required driver from http://dev.mysql.com/downloads/connector/j/. Once downloaded, you can install the driver by copying the driver JAR file into the JIRA_INSTALL/lib directory. After that, you need to restart Jira. If you have installed Jira as a Windows service in step 9, refer to the Starting and stopping Jira section.

Note

Make sure that you select the Platform Independent option and download the JAR or TAR archive.

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 six of the installation process.

The steps are explained in the following sections.

Step one

In the first step of the wizard, we need to select how we want Jira to be set up. Since we are installing Jira for production use, we will select the I'll set it up myself option, as demonstrated in the following screenshot:

Step two

For the second step, we will need to select the database we want to use. This is where we configure Jira to use the MySQL database we created earlier in this chapter. If you select the Built In option, Jira will use its bundled in-memory H2 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 for getting 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.

Once you have filled in the details for your database, it's 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 a success message. You should be able to move onto the next step by clicking on 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 three of the wizard.

Step three

In the third step, you will need to provide some basic details about this Jira instance. Once you have filled in the requisite fields, click on Next to move on to step four of the wizard:

Step four

In the fourth step, we need to provide a license key for Jira. If you have already obtained a license from Atlassian, you can paste it into the Your License Key text box. If you do not have a license, you can generate an evaluation license by clicking on the generate a Jira trial license link. The evaluation license will grant you access to Jira's full set of features for one month. After the evaluation period ends, you will lose the ability to create new issues, but you can still access your data:

Step five

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 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. Fill in the administrator account details and click on Next to move on to the sixth step:

Note

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

Step six

In the sixth step, you can set up your email server details. Jira will use the information configured here to send out notification emails. Notification is a very powerful feature in Jira and one of the primary methods by means of which Jira communicates with users. If you do not have your email server information handy, you can skip this step for now by selecting the Later option and clicking on Finish. You can configure your email server settings later, as you will see in Chapter 8, Emails and Notifications:

Congratulations! You have successfully completed your Jira setup. You should now see the welcome page, and be automatically logged in as the administrator user you created in step five. On the welcome page, you will need to set up a few user preferences, such as the default language and profile picture. Follow the onscreen prompts to set up the account, and once you are done, you should be presented with the options to create a sample project, a new project from scratch, or import project data from other sources, as shown in the following screenshot:

Starting and stopping Jira

Since we used the Windows Installer, Jira is installed as a Windows service. Therefore, 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:

 

Post-installation configurations


The post-installation configuration steps are optional, depending on your needs and environment. If you set up Jira for evaluation purposes, you probably do not need to perform any of the following steps, but it is always good practice to be familiar with these as a reference.

Note

You will need to restart Jira after making the changes that will be discussed in the next section.

Increasing Jira's memory

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, as we described in this chapter, you can increase the memory as follows:

  1. Find the JIRA Windows service name. You can do this by going to the Windows services console and double-clicking on the Atlassian JIRA service. The service name will be the part after //RS// in the Path to executable field, for example, JIRA150215215627.
  2. Open a new Command Prompt and change the current working directory to the JIRA_INSTALL/bin directory.
  3. Run the following command by substituting the actual service name for Jira:
tomcat7w //ES//<JIRA Windows service name>
  1. Select the Java tab, update the Initial memory pool and Maximum memory pool sizes, and click on OK:
  1. Restart Jira to apply the change.

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 (4,096 m) of memory is enough to support a fairly large instance of Jira used by hundreds of users.

Note

Make sure that you have sufficient physical RAM available before allocating instances to Jira.

Changing Jira's port number and context path

As part of the installation process, the installation wizard prompted us to decide which port JIRA should listen to 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 the 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.

Configuring HTTPS

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:

  1. Obtain and install a certificate
  2. Enable HTTPS on your application server (Tomcat)
  3. Redirect traffic to HTTPS

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 that's been 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 RSAkeytool -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 then you 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.

 

Summary


Jira is a powerful, yet simple, application, as reflected in its straightforward installation procedures. You have a wide variety of options available so that you can choose how you would like to install and configure your copy. You can mix-and-match different aspects, such as operating systems and databases, to best suit your requirements. The best part is that you can have a setup that consists entirely of open source software, which will bring down the cost and provide you with a reliable infrastructure at the same time.

In the next chapter, we will start to explore various aspects of Jira. The following chapters, starting with projects, will talk about key concepts in any Jira installation.

About the Author

  • Patrick Li

    Patrick Li is the cofounder of AppFusions and works there as a senior engineer. AppFusions is one of the leading Atlassian experts, specializing in integration solutions with many enterprise applications and platforms, including IBM Connections, Jive, Google Apps, and more. He has worked in the Atlassian ecosystem for over 9 years, developing products and solutions for the Atlassian platform and providing expert consulting services. He has authored many books and video courses covering Jira 4 to 8. He has extensive experience in designing and deploying Atlassian solutions from the ground up, and customizing existing deployments for clients across verticals such as healthcare, software engineering, financial services, and government agencies.

    Browse publications by this author

Latest Reviews

(4 reviews total)
Very cheap and affordable books for learning.
That's a nice book to read!
Great collections of books.

Recommended For You

Book Title
Access this book, plus 8,000 other titles for FREE
Access now