JIRA 7 Administration Cookbook - Second Edition

Open up a new command prompt on the MySQL server.

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

Enter the password for the user when prompted.

Create a new database for JIRA by running the following command:

        create database jiradb character set utf8;

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 created a new database named jiradb and a new database user named jirauser. We will use these details later to connect JIRA with MySQL. The next step is to install JIRA.

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

Create a new directory on the filesystem where JIRA will be installed. This directory will be referred to as JIRA_INSTALL.

Create another directory on the filesystem. This will be used for JIRA to store its attachments, search indexes, application data, 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.

Unzip the JIRA archive file in the JIRA_INSTALL directory.

Change both the JIRA_INSTALL and JIRA_HOME directories' owner to the new JIRA user.

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

Locate the jira.home= line in this file.

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 

Copy the database driver JAR file (obtained from the Getting ready section) to the JIRA_INSTALL/lib directory.

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. You should see the output Tomcat started in your console; this means that JIRA is up and running.

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

Open up a browser and go to http://localhost:8080 (replace localhost with the actual server name). 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.

The first step is to select how you want JIRA to be set up. Select the I'll set it up myself option and click on the Next button.

The second step is to set up the database information. Select the My Own Database (recommended for production environments) option.

Select a value for the Database Type option. For this recipe, select the MySQL option.

Enter the details for our new jiradb database.

Click on Test Connection to check whether JIRA is able to connect to the database.

Click on the Next button to proceed if the database connection test is successful and move to the next step of the wizard.

Enter the Application title value for this JIRA instance.

Select Public if you would like to let people sign up for accounts or Private if you want only administrators to create accounts. For most organizations that use JIRA to track internal projects, this will be in Private mode.

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.

Click on Next to go to the third step of the wizard, as shown in the following screenshot:

Enter your JIRA license key if you have one. If you do not have a license key, you can generate a temporary trial license by visiting https://my.atlassian.com and creating an account.

Click on Next to go to the next step of the wizard, as shown in the following screenshot:

Enter the details for the initial administrator account. The user account will have access to all the configuration options in JIRA, so make sure you do not lose its login credentials.

Click on Next to go to the fifth and final step of the wizard, as shown in the following screenshot:

Choose whether 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.

Click on Finish to complete the setup process.

Take your current JIRA offline, for example, by running the stop-jira.bat script.

Back up the JIRA database with its native backup utility.

Launch the installer and select the Upgrade an existing JIRA installation option.

Now, select the directory where the current JIRA is installed:

Check the backup JIRA home directory option and click on the Next button.

Review the upgrade checklist and click on the Upgrade button.

Wait for the installer to complete the upgrade process. Once the upgrade is complete, the installer will automatically launch JIRA.

Update add-ons once JIRA successfully starts.

Take your current JIRA offline.

Install the new version of JIRA into a different directory.

Edit the jira-application.properties file in the new version of JIRA, which is located in the JIRA_INSTALL/atlassian-jira/WEB-INF/classes directory.

Update the value of jira.home to the current JIRA_HOME directory or to a copy of this directory.

Copy any modified files from the old JIRA instance into the new one.

Start up the new JIRA instance.

Update the add-ons once JIRA starts successfully.

Remove the previous installation directory to avoid confusion.

Download and install a brand new JIRA instance in your new environment with an empty database.

Take your current JIRA offline.

Back up your current JIRA database with its native backup utility.

Back up your current JIRA_HOME directory.

Then, take your new JIRA offline.

Copy over your JIRA_HOME backup and replace the new JIRA_HOME directory with it.

Update the dbconfig.xml file with the new JIRA database details.

Copy your database backup and restore the new JIRA database.

Start up the new JIRA instance.

Next, log in to JIRA as a JIRA administrator.

Select System info from the Administration panel.

Note down the files listed in the Modified Files and Removed Files sections.

Review and apply the same changes to the new JIRA instance.

Shut down JIRA if it is running.

Open up JIRA_INSTALL/conf/server.xml in a text editor.

Locate the following line and enter the context path for the path attribute—for example, path="/jira":

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

Save the file and restart JIRA. If you are doing this after JIRA is installed, you will have to update JIRA's Base URL option so that its links will reflect the change.

Then, log into JIRA as an administrator.

Navigate to Administration | Systems | General Configuration.

Click on the Edit Settings button.

Enter the fully qualified URL into JIRA, including the context path in the Base URL field.

Click on Update to apply the change.

Open up a command window and go to the directory where the certificate file resides.

Generate a Java KeyStore (JKS) for JIRA by running the keytool -genkey -alias jira -keyalg RSA -keystore JIRA_INSTALL/jira.jks command.

Import the certificate into KeyStore repository by running the keytool -import -alias jira -keystore JIRA_INSTALL/jira.jks -file file.crt command, where file.crt is the certificate file.

Open the server.xml file located in the JIRA_INSTALL/conf directory in a text editor.

Locate and uncomment the following XML 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"/>

Add a few new attributes to the Connector tag and save the file, as follows:

        keystoreFile="PATH_TO_YOUR_KEYSTORE" 
        keystorePass="PASSWORD_FOR_YOUR_KEYSTORE" 
        keyAlias="jira" 
        keystoreType="JKS" 

Restart JIRA to apply the changes.

Open the command prompt and go to the JIRA_INSTALL/bin directory.

Depending on your OS, run the config.bat (Windows) or config.sh (Linux / OS X) file.

Select the Web Server tab from the JIRA Configuration Tool window.

Select the HTTP and HTTPs (redirect HTTP to HTTPs) option for Profile.

Click on the Save button at the bottom of the window, as shown in the following screenshot.

Restart JIRA to apply the change.

Open the web.xml file located in the JIRA_INSTALL/atlassian-jira/WEB-INF directory.

Add the following XML snippet at the end of the file just before the closing </webapp> tag:

        <security-constraint> 
          <display-name>HTTP to HTTPs
          Redirection</display-name> 
          <web-resource-collection> 
            <web-resource-name>all-except-
            attachments</web-resource-name> 
            <url-pattern>*.jsp</url-pattern> 
            <url-pattern>*.jspa</url-pattern> 
            <url-pattern>/browse/*</url-pattern> 
          </web-resource-collection> 
          <user-data-constraint> 
            <transport-
            guarantee>CONFIDENTIAL</transport-
            guarantee> 
          </user-data-constraint> 
        </security-constraint> 

Restart JIRA to apply the change.

Open up a command prompt and go to the directory where the certificate file resides.

Import the certificate into the trust store by running the keytool -import -alias tomcat -file file.cer JAVA_HOME\jre\lib\security\cacerts command, where file.cer is the certificate file.

Restart JIRA to apply the changes.

Connect to the JIRA database with a client tool by running the mysql -u jirauser -p command, where jirauser is the username used by JIRA to access the JIRA database.

You can find JIRA's database details from the dbconfig.xml file located in JIRA_HOME.

Change to the JIRA database by running the use jiradb command, where jiradb is the name of JIRA's database.

Determine the groups that have the JIRA System Administrators global permission with the following SQL statement:

        select perm_parameter from 
        schemepermissions where PERMISSION=44;

Find users that belong to the groups returned in STEP 4 by running the following SQL statement, where jira-administrators is a group returned from STEP 4:

        select child_name, directory_id
        from cwd_membership where
        parent_name='jira- administrators';

Reset the user's password in the database with the following SQL statement, where admin is a user returned in STEP 5:

        update cwd_user set
        credential='uQieO/1CGMUIXXftw3ynrsaYLShI+
        GTcPS4LdUGWbIusFvHPfUzD7
        CZvms6yMMvA8I7FViHVEqr6Mj4pCLKAFQ==' where
        user_name='admin';

Restart JIRA to apply the change.

Log into JIRA as an administrator.

Select the Projects menu from the top and select the Import External Project option.

Then, select the system from the list that comes out of the box with JIRA. If your system is not listed, select the CSV option.

Select the CSV file for the CSV Source File field. If you are performing an import for the first time, do not select the Use an existing configuration option. We will generate the configuration at the end of the import, and you will be able to use this to fast-track future imports.

Expand the Advanced option if your file uses a different file encoding or uses a character other than comma (,) as its separators. Click on the Next button to go to Step 2 of the wizard.

Select the project to import your data into. If you do not have the project, you can select the Select New option and create a project on the spot.

Varify the E-mail Suffix for New Users and Date format values used in your CSV file. This will ensure that data such as dates will be correctly parsed during import and saved in JIRA's date fields, such as Due dates.

Select and map the CSV columns to JIRA fields. Certain fields, such as the Summary field, must have a corresponding column in the file. Otherwise, JIRA will not allow you to proceed. If you do not want to map a column, you can select the Don't map this field option.

Select the Map field value option for any columns mapping to a select list style field. This will allow you to map individual values from the CSV file column to the options available in JIRA. Unless you are sure that your file contents can be mapped to the JIRA field options exactly, it is best to manually verify this; otherwise, you would end up with duplicated values due to things such as case sensitivity.

If you select to map field values, review each of the listed values and map them to their corresponding field options in JIRA. If a value does not have an option, you can type in the desired option for JIRA to create.

Click on the Begin Import button to start importing your data into JIRA.

After the import process is completed, review the import result. You can click on the download a detailed log link to get a full log of the process if the import fails. You can also click on the save the configuration link to get a copy of the mapping files so that next time, you do not have to remap everything from scratch.