JIRA 6.x Administration Cookbook

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

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 in. 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, 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 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.

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

The first step is to select the language JIRA will use for its user interface.

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 Next to move to the second step of the wizard as shown in the following screenshot:

Enter the title for this JIRA instance.

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.

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.

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.

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.

Select the I have a key option if you have a valid JIRA license key handy.

Click on Next to go to the fourth 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 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 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.

Click on Finish to complete the setup process, as shown in the following screenshot:

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.

Select the directory where the current JIRA is installed:

Check the Back up 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 has successfully started.

Back up the JIRA database with its native backup utility

Back up the JIRA_INSTALL directory

Back up the JIRA_HOME directory

Get a list of all the customized files in the JIRA_INSTALL directory from the System Info page in JIRA

For the WAR distribution, prepare and configure the installation files

Take your current JIRA offline.

Install the new version of JIRA.

Edit the jira-application.properties file in this version of JIRA, 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 that directory.

Copy any modified files.

Start up the new JIRA.

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.

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.

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

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

Save the file and restart JIRA.

If you have updated the context path for JIRA after it is installed, you will have to update JIRA's Base URL option so that all its links will reflect the change.

Log in to 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 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:

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 or config.sh 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.

Log in to JIRA as a JIRA administrator.

Navigate to Administration | System | Configure SSL.

Type in the target system's address in the Rules textbox in the host:port format (for example, smtp.gmail.com:465).

Click on Save certificates as shown in the following screenshot.

Follow the instruction on the screen to copy over the cacerts file to the target location.

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 to access the JIRA database.

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 3 using the following SQL statement, where jira-administrators is a group returned from step 3:

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

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

Restart JIRA to apply the change.

Log in to JIRA as a JIRA administrator.

Navigate to Administration | System | Generate Metadata:

Set the number of projects and other metadata to generate.

Click on Generate and wait for the process to complete.

Select Generate Data.

Set the number of issues, comments, and other data that is to be generated.

Click on Generate and wait for the process to complete, as shown in the following screenshot:

Unzip the jira_anon.zip file to a temporary directory.

Copy your JIRA XML export (entities.xml) to the temporary directory.

Open up a command prompt and go to the temporary directory where the joost.jar file resides.

Run the anonymizer application with the java -Xmx512m -jar joost.jar entities.xml anon.stx > anon-entities.xml command, where entities.xml is the name of the original XML export and anon-entities.xml is the new anonymized XML file to be created.