Installing JIRA for production use

In this recipe, we will look at how to install and set up JIRA in a production environment. This includes setting up a dedicated user to run JIRA under and using an external database.

We will be using the standalone archive distribution, as the steps are consistent across both Windows and Linux platforms.

Getting ready

The following things need to be checked before you start with this recipe:

• Download the latest JIRA archive distribution from https://www.atlassian.com/software/jira/download and click on the All JIRA Download Options link.
• Make sure your server environment meets JIRA's requirements by visiting the following link: https://confluence.atlassian.com/display/JIRA/Supported+Platforms.
• Install Java on the system. At the time of writing, JIRA 6 required Java 7. Make sure you get the latest update for Java, unless it is explicitly stated as unsupported by JIRA.
• Make sure the JAVA_HOME or JRE_HOME environment variable is configured.
• Have a database system available, either on the server hosting JIRA or a different server accessible over the network. For this recipe, we will be using MySQL; if you are using a different database, change the commands and queries accordingly.
• Download the necessary database driver. For MySQL, you can download it from https://dev.mysql.com/downloads/connector/j.

How to do it…

We first need to create an empty MySQL database for JIRA:

1. Open up a new command prompt on the MySQL server.
2. Run the following command (you can also use another user instead of root as long as the user has permission to create new users and databases):

   mysql -u root -p

3. Enter the password for the user when prompted.
4. Create a new database for JIRA by running the following command:

   create database jiradb character set utf8;

5. Create a new user for JIRA in the database and grant the user access to the jiradb database we just created using the following command:

   grant all on jiradb.* to 'jirauser'@'localhost' identified by 'jirapassword';

   In the previous five steps, we have created a new database named jiradb and a new database user named jirauser. We will be using these details later to connect JIRA with MySQL. The next step is to install JIRA.

6. Create a dedicated user account to run JIRA under. If you're using Linux, run the following command as root or with sudo:

   useradd --create-home --comment "Dedicated JIRA account" --shell /bin/bash jira

   Note

   It is a good practice to reduce security risks by locking down the user account so that it does not have login permissions.

7. Create a new directory on the filesystem where JIRA will be installed in. This directory will be referred to as JIRA_INSTALL.
8. Create another directory on the filesystem. This will be used for JIRA to store its attachments, search indexes, and other information. You can create this directory on a different drive with more hard disk capacity, such as a network drive (this could slow down the performance). This directory will be referred to as JIRA_HOME.

   Note

   It is a good practice to keep the JIRA_INSTALL and JIRA_HOME directories separate, that is, the JIRA_HOME directory should not be a subdirectory inside JIRA_INSTALL. This will make future upgrading and maintenance easier.

9. Unzip the JIRA archive file in the JIRA_INSTALL directory.
10. Change both the JIRA_INSTALL and JIRA_HOME directories' owner to the new JIRA user.
11. Open the JIRA_INSTALL/atlassian-jira/WEB-INF/classes/jira-application.properties file in a text editor.
12. Locate the jira.home= line in this file.
13. Cut and paste this in the full path to the JIRA_HOME directory and remove the # symbol if present. Make sure you use the forward slash (/). The following line shows how it looks on a Linux system:

    jira.home=/opt/data/jira_home

    Note

    Windows uses the backward slash (\) in the file path. You should still use the forward slash (/) while specifying the jira.home directory.

14. Copy the database driver JAR file to the JIRA_INSTALL/lib directory.
15. Start up JIRA by running the start-jira.sh (for Linux) or start-jira.bat (for Windows) script from the JIRA_INSTALL/bin directory as the JIRA user.

    JIRA comes with a setup wizard that will help guide us through the final phase of the installation.

16. Open up a browser and go to http://host:8080. By default, JIRA runs on port 8080. You can change this by changing the connector port value in the JIRA_INSTALL/conf/server.xml file.
17. The first step is to select the language JIRA will use for its user interface.
18. The second step is to set up the database information. Select the My Own Database (recommended for production environments) option.
19. Select a value for the Database Type option. For this recipe, select the MySQL option.
20. Enter the details for our new jiradb database.
21. Click on Test Connection to check whether JIRA is able to connect to the database.
22. Click on Next to move to the second step of the wizard as shown in the following screenshot:
    
23. Enter the title for this JIRA instance.
24. Select Public if you would like to let people sign up for accounts, or select Private if you want only administrators to create accounts. For most organizations that use JIRA to track internal projects, it will be the Private mode.
25. Set the Base URL option. The base URL is the one that users will use to access JIRA. Usually, this should be a fully qualified domain name or the hostname, that is, not a localhost or an IP address.
26. Click on Next to go to the third step of the wizard, as shown in the following screenshot:
    
27. Enter your JIRA license key.
28. Select the I don't have an account option if you do not have a valid JIRA license and you do not have an account on my.atlassian.com.
29. Select the I have an account but no key option if you have an account on my.atlassian.com but you do not have a valid JIRA license key.
30. Select the I have a key option if you have a valid JIRA license key handy.
31. Click on Next to go to the fourth step of the wizard, as shown in the following screenshot:
    
32. Enter the details for the initial administrator account. The user account will have access to all configuration options in JIRA, so make sure you do not lose its login credentials.
33. Click on Next to go to the fifth and final step of the wizard, as shown in the following screenshot:
    
34. Choose if you want to set up an outgoing SMTP server now or later. If you do not have an SMTP server ready right now, you can always come back and configure it later.
35. Click on Finish to complete the setup process, as shown in the following screenshot:
    

Once JIRA finishes the final setup procedures, you will be automatically logged in with the initial administrator account you created.

There's more…

By default, JIRA is set to use a maximum of 768 MB of memory. For a production deployment, you might need to increase the amount of memory allocated to JIRA. You can increase this by opening up the setenv.sh (on Linux) or setenv.bat (on Windows) file in the JIRA_INSTALL/bin directory and changing the value for the JVM_MAXIMUM_MEMORY parameter. For example, if we want to set the maximum memory to 2 GB, we will change it to JVM_MAXIMUM_MEMORY="2048m". You will need to restart JIRA after performing this change. For production uses, it is recommended that you allocate at least 2 GB of memory to the JIRA JVM.

If you are using LDAP for user management in your organization, refer to the Integrating with LDAP for authentication only recipe in Chapter 4, User Management.