Home Business & Other JIRA 5.2 Essentials - Second Edition

JIRA 5.2 Essentials - Second Edition

By Patrick Li
books-svg-icon Book
eBook $42.99 $29.99
Print $70.99
Subscription $15.99 $10 p/m for three months
$10 p/m for first 3 months. $15.99 p/m after that. Cancel Anytime!
What do you get with a Packt Subscription?
This book & 7000+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with a Packt Subscription?
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with eBook + Subscription?
Download this book in EPUB and PDF formats, plus a monthly download credit
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with a Packt Subscription?
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with eBook?
Download this book in EPUB and PDF formats
Access this title in our online reader
DRM FREE - Read whenever, wherever and however you want
Online reader with customised display settings for better reading experience
What do you get with video?
Download this video in MP4 format
Access this title in our online reader
DRM FREE - Watch whenever, wherever and however you want
Online reader with customised display settings for better learning experience
What do you get with video?
Stream this video
Access this title in our online reader
DRM FREE - Watch whenever, wherever and however you want
Online reader with customised display settings for better learning experience
What do you get with Audiobook?
Download a zip folder consisting of audio files (in MP3 Format) along with supplementary PDF
What do you get with Exam Trainer?
Flashcards, Mock exams, Exam Tips, Practice Questions
Access these resources with our interactive certification platform
Mobile compatible-Practice whenever, wherever, however you want
BUY NOW $10 p/m for first 3 months. $15.99 p/m after that. Cancel Anytime!
eBook $42.99 $29.99
Print $70.99
Subscription $15.99 $10 p/m for three months
What do you get with a Packt Subscription?
This book & 7000+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with a Packt Subscription?
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with eBook + Subscription?
Download this book in EPUB and PDF formats, plus a monthly download credit
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with a Packt Subscription?
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with eBook?
Download this book in EPUB and PDF formats
Access this title in our online reader
DRM FREE - Read whenever, wherever and however you want
Online reader with customised display settings for better reading experience
What do you get with video?
Download this video in MP4 format
Access this title in our online reader
DRM FREE - Watch whenever, wherever and however you want
Online reader with customised display settings for better learning experience
What do you get with video?
Stream this video
Access this title in our online reader
DRM FREE - Watch whenever, wherever and however you want
Online reader with customised display settings for better learning experience
What do you get with Audiobook?
Download a zip folder consisting of audio files (in MP3 Format) along with supplementary PDF
What do you get with Exam Trainer?
Flashcards, Mock exams, Exam Tips, Practice Questions
Access these resources with our interactive certification platform
Mobile compatible-Practice whenever, wherever, however you want
  1. Free Chapter
    Getting Started with JIRA
About this book
Atlassian's JIRA provides issue tracking and project tracking for software development teams to aid speed of development and quality of code. This book will show you how to develop software more efficiently by planning, designing, and customizing your own JIRA implementation.JIRA is a popular issue tracking product designed for better bug tracking, issue tracking, and project management. JIRA 5.2 Essentials provides a comprehensive guide covering everything you will need to plan, set up, design, customize, and manage your software development projects efficiently and to a professional standard.In this practical book you will learn how to design and implement JIRA for project and issue tracking. You will jump into the installation and design of JIRA before going through the required techniques to effectively manage issues that threaten your software development project.Each chapter builds on the last, taking you through important concepts and techniques such as business processes and workflows, setting up e-mail notifications, field and screen management, and reporting. Using these techniques you will be able to make JIRA adapt to your organization and save time and energy by developing software more efficiently.Newly improved and updated to JIRA 5.2 this book also includes a section about GreenHopper and Agile development with JIRA.
Publication date:
April 2013
Publisher
Packt
Pages
396
ISBN
9781782179993

 

Chapter 1. Getting Started with JIRA

JIRA has always been a fun to use and easy to install software, and JIRA 5 is no different. In fact, JIRA 5 has improved on its predecessors by providing a more polished and powerful installation wizard, eliminating some of the old installation steps where users had to manually edit configuration files in a text editor.

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

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

  • 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

 

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 available. This will help you make an informed decision and be better prepared for future maintenance and troubleshooting.

High-level architecture

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:

Web browsers

JIRA is a web application, so there is no need for users to install anything on their machine. All they need is a web browser that is compatible with JIRA. Since JIRA 4, JIRA has made some major changes to its user interface, and JIRA 5 has continued to improve upon this to deliver a more responsive user experience. As a result, some of the older browsers are no longer supported. The following table summarizes the browser requirements for JIRA:

Browsers

Compatibility

Microsoft Internet Explorer

8.0, 9.0 (Compatibility View is not supported)

10 is not supported

Mozilla Firefox

Latest stable versions

Safari

Latest stable versions

Google Chrome

Latest stable versions

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 6, Workflows and Business Processes and Chapter 7, E-mails 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 issues and projects, are stored in a relational database. Contents 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 used is transparent to the users and you can migrate from one database to another with ease.

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

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:

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 the backup files from this directory.

log

This directory contains the JIRA logs.

plugins

This directory is where the installed add-ons are stored. In the previous versions of JIRA, add-ons were installed by copying the add-on files to this directory manually, but in JIRA 5, you will no longer need to do this, unless specifically instructed to do so. 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 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.

Tip

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

 

System requirements


Just like any software applications, there is a set of base requirements that need to be met before you can install and run JIRA, so it is important for you to be familiar with these requirements so you can plan out your deployment successfully. Note that these requirements are for a behind-the-firewall deployment. Atlassian also offers a SaaS based alternative called Atlassian OnDemand http://www.atlassian.com/software/ondemand/overview.

Hardware requirements

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:

  • Number of users in the system

  • Number of issues and projects in the system

  • Number of concurrent users, especially during peak hours

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.

Software requirements

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.

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, existing organization IT infrastructure and requirements.

The operating systems supported by Atlassian are Windows and Linux. There is a distribution for Mac OSX, however, it is not officially supported. With both Windows and Linux, Atlassian provides an executable installer wizard package that 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. So, if you do not have any preferences and would like to keep the initial cost down, 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 the archive distributions, you will need to make sure that you have the required Java environment installed and configured.

JIRA 5 supports Java 6 or 1.6, from update 18 and above. If you run JIRA on an unsupported Java version, including its patch version, you may run into unexpected errors.

Java platforms

Support status

Oracle JDK/JRE

1.6 (update 18 or higher is required, update 24 or higher is recommended).

1.7 is supported starting with JIRA 5.2.

Databases

JIRA stores all its data in a relational database. While you can run JIRA with HSQLDB, the in-memory database that comes bundled with JIRA, it is prone to data corruption. For this reason, it is important that you use an enterprise database for production systems.

Most relational databases available in 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 standards. If you run Windows as your operating system, then you might probably want to go with 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 list of 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.x (excluding 5.0)

Requires JDBC Connector/J 5.1

PostgreSQL

PostgreSQL 8.3, 8.4

Requires PostgreSQL Driver 8.4.x

Microsoft SQL Server

SQL Server 2008

SQL Server 2005

Requires JTDS 1.2.4 driver

Oracle

Oracle 11g

Requires Oracle 11.2.x driver

HSQLDB

Bundled with standalone distribution

Take a special note of the driver requirements on each database, as some drivers that come bundled with the database vendor are not supported. If you are using the standalone distributions, the necessary drivers are included with JIRA.

Application servers

Unlike the previous versions of JIRA, JIRA 5 officially only supports Apache Tomcat as the application server. While it is possible to deploy JIRA into other application servers, you will be doing this at your own risk.

The following table shows the versions of Tomcat that are supported by JIRA 5:

Application server

Support status

Apache Tomcat

Tomcat 5.5.27 – 5.5.29

Tomcat 6.0.32

Tomcat 7.0.29 is supported starting JIRA 5.2

 

Installation options


JIRA comes in two distributions, the standalone and WAR distributions. Fundamentally, there are no differences between them. The major difference is that the standalone distribution comes bundled with Apache Tomcat, an in-memory database, and Java if you use the executable installer version.

As you can see, the standalone distribution comes with everything required to get JIRA installed. As mentioned earlier, the standalone distribution comes in two flavors, an executable installer and a 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 ZIP 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 install JIRA as a service. However, you do get the advantage of learning what really goes on under the hood.

The WAR distribution is for more advanced users who are familiar with the Java EE application deployment model. With the WAR distribution, you have to make the necessary changes to the configuration files, build your own deployable JIRA, and then deploy it to an application server; in this case, Tomcat. The advantage of using the WAR distribution is that it is very easy for you to version and control all the changes you make to the standard distribution files, which makes future upgrades much easier.

 

Installing 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 that will be ready for a small production team. We will be performing our installation on a Windows platform with a MySQL database server. If you are planning to use a different platform or database, please refer to the vendor documentation on installing the required software for your platform.

In this exercise, you will:

  1. Install a fresh instance of JIRA.

  2. Configure JIRA to an enterprise relational database.

  3. Configure JIRA as a service so it will start automatically with the system.

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

For our deployment, we will be using the following:

  • JIRA standalone distribution 5.2.5

  • MySQL 5.5.27

  • Java Development Kit 6 Update 33

  • Microsoft Windows 7

Installing Java

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:

  1. Download the latest JDK from http://java.sun.com/javase/downloads.

    Note

    At the time of writing, the latest version of Java 6 is JDK 6 Update 39.

  2. Double-click on the downloaded installation file to start the installation wizard.

  3. 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 rest of the book.

  4. Create a new environmental variable named JAVA_HOME with the value of where you installed Java:

  5. Test the installation by typing the following command in a new command prompt:

    java -version
    

    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.

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

  1. Download MySQL from http://dev.mysql.com/downloads.

    Note

    At the time of writing, the latest version of MySQL is 5.6.10

  2. Double-click on the downloaded installation file to start the installation wizard.

  3. Click on Next on the welcome screen.

  4. Select the Typical setup 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. Once the installation is completed, make sure you select the Configure MySQL Server now option and click on Finish. This will bring up the MySQL configuration wizard:

  6. From the MySQL configuration wizard, select Standard Configuration.

  7. Select both the Install As Windows Service and Include Bin Directory in Windows PATH options on the next screen. This will display the MySQL startup when the system starts up and also allow you to run the MySQL command-line tools directly:

  8. Configure the MySQL root user password. The username will be root.

  9. Click on Execute on the next screen and MySQL will start applying the configuration options.

Prepare MySQL for JIRA

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

  1. Start a new command prompt.

  2. Issue the following command to connect to MySQL:

    mysql –u root -p
    
  3. When prompted for a password, enter the password you chose during configuration. This will bring up the interactive shell for MySQL.

  4. Issue the following command to create a database:

    create database jiradb character set utf8;
    
  5. 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. You need to ensure that the database uses the InnoDB storage engine to avoid data corruption.

  6. Issue the following command:

    grant all on jiradb.* to 'jirauser'@'localhost' identified by 'jirauser';
    
  7. We are doing several things here. First, we create a user called jirauser and assign the password jirauser to him. You should change the username and password to something else.

  8. We have also granted all the privileges to the user for the database jiradb 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 in step 3, then make sure you change the command so that it uses your database name.

  9. 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.

  10. To verify your setup, exit the current interactive session by issuing the following command:

    quit;
    
  11. Start a new interactive session with your newly created user:

    mysql –u jirauser –p
    
  12. You will be prompted for a password, which you have set up in the previous command as jirauser.

  13. Issue the following command:

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

  15. Examine the jiradb database by issuing the following commands:

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

  17. The second command lists all the tables that exist in the jiradb database. Right now, the list should be empty, since tables have been created for JIRA now, 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 install JIRA. Normally, there are only two steps—create and set up the JIRA_HOME directory and run through the JIRA setup wizard.

Obtaining and installing JIRA

The first step is to download the latest stable release of JIRA, and install the necessary files to the JIRA_INSTALL directory:

  1. 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 the installation package for you to download. If you intend to install JIRA on a different operating system than the one you are currently on, make sure you select the correct operating system package.

  2. As mentioned earlier, with Windows, there is a Windows installer package and a self-extracting ZIP package. For the purpose of this exercise, we will use the self-extracting option as this will provide us with an insight of the steps usually hidden by the installation programs.

  3. Unzip the downloaded file to your intended JIRA_INSTALL directory.

    Tip

    Atlassian also offers installer packages for Windows and Linux, which can help you quickly get the setup.

Configuring jira-application.properties

The next step is to create the JIRA_HOME directory. As we have discussed earlier in the chapter, this is where JIRA keeps its data such as configurations, indexes, and attachments. It is usually a good practice to create this directory in a separate location where JIRA is installed; in other words, where the JIRA_INSTALL directory is:

  1. Create a new directory on your filesystem. In this example, we will call it JIRA_HOME.

  2. Open the JIRA_INSTALL\atlassian-jira\WEB-INF\classes\jira-application.properties file in a text editor.

  3. Locate the following line:

    #jira.home = 
  4. Fill in the full path to your JIRA_HOME directory and save the file:

    jira.home = C:/JIRA_HOME

    Note

    Make sure that you remove # at the front and use a forward slash (/) instead of a backward slash (\).

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.

Tip

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

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:

Property

Description

Application Title

This is the title given to your JIRA.

Mode

Public will allow user signup.

Private will disable user signup and only allow administrators to create users.

Base URL

This is the URL used to access your JIRA. It will be used for links generated by JIRA.

License Key

This is a valid license key for your JIRA. It can be either a full license or an evaluation license.

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.

Configuring JIRA as a service

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:

  1. Start a new command prompt and browse to the JIRA_INSTALL/bin directory.

  2. Run the following command:

    service.bat install JIRA
    
  3. This will install JIRA as a Windows service. The name of the service will be Atlassian JIRA, followed by the name you supplied after the install command. So in your example, the name of the service will be Atlassian JIRA:

  4. Verify the configuration by going to Settings | Administrative Tools | Services:

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

 

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 a good practice to be familiar with these as a reference:

Configuring the application server

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:

  • Line 1: 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.

  • Line 2: 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.

  • Line 3: 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 through the URL of 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 through the URL of http://localhost:8080/jira.

Configuring HTTPS

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:

  • Obtain and install a certification

  • Enable HTTPS on your application server (Tomcat)

  • Redirect traffic to HTTPS

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.

Installing the database drivers

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:

  1. Obtain the database driver from the vendor.

  2. Copy the driver (usually a JAR file) into your JIRA_INSTALL/lib directory.

  3. Restart JIRA so the driver can be properly loaded.

Managing the database setup

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.

Note

Before you make any changes, make sure you make a back up of the dbconfig.xml file, in case you need to roll back the changes.

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.

 

Summary


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

Now that you have a working instance of JIRA, we will start to explore various aspects of JIRA in the following chapters, starting with projects, which are the first key components in any JIRA installation.

About the Author
  • Patrick Li

    Patrick Li is the cofounder of AppFusions and works as a senior engineer there, 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 10 years, developing products and solutions for the Atlassian platform and providing expert consulting services. He has authored many books and video courses covering Jira. 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
JIRA 5.2 Essentials - Second Edition
Unlock this book and the full library FREE for 7 days
Start now