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.