Atlassian Integration Guide : Dragons with JIRA Stage 1 - Set Up Environment and JIRA


Beware, all ye who enter, for here there be dragons. You are embarking on stage 1 of the Atlassian Dragon Quest.

In this stage, you will install Java and a database (PostgreSQL) to hold the data for your Atlassian applications. Then you will configure some JIRA options, and create a project and dashboard for use in the subsequent stages of this integration procedure.

(info) This procedure assumes that you already have JIRA installed. If you do not yet have JIRA, please ignore this page and start at Here Be Dragons instead.

Time estimate: This stage will take approximately 60 minutes.

On this page:

Step 1. Check your Java Development Kit

Requirements: Oracle JDK 1.6.x. Note that the JRE alone is not enough.

If you do not have the right version of the Java Development Kit (JDK) already installed, follow the steps below to get it.

  1. Download the Oracle Java SE Development Kit (JDK).
    • Get the latest version of the JDK 1.6, at least version 6u23 or later.
    • If you are running 64-bit Windows, we recommend that you use 32-bit JDK rather than the 'x64' JDK. The 32-bit version will use less memory. You do not need the 64-bit JDK unless you are running a very large server.
  2. Follow the Oracle installation instructions.
  3. Make sure you have a JAVA_HOME environment variable pointing to the root directory of the JDK. Some JDK installers set this automatically.
    • Check by typing one of the following into a command window, depending on your operating system.
      • On Windows: echo %JAVA_HOME%
      • On Linux or UNIX: echo $JAVA_HOME
    • If the above command does not show you the path to your JDK, please refer to the Crowd instructions on setting JAVA_HOME.

Step 2: Install your PostgreSQL Database Server

Below are the instructions for installing and setting up a PostgreSQL database server. If your JIRA installation is already using a different supported database server and you have a good technical knowledge of that server, you can choose to use that database for your other applications too. However, for the purposes of this integrated setup exercise we do recommend PostgreSQL. Note that you will need the database server to hold the data for the other Atlassian applications that you will set up in later stages of this integration exercise.

Requirements: PostgreSQL version 8.4.x.

  1. Download PostgreSQL – Get the latest 8.4.x. Note that Atlassian does not support PostgreSQL 9.x. For the simplest installation, choose one of the one-click installers.
  2. Install PostgreSQL. If you chose one of the PostgreSQL one-click installers, this is simple: Run the executable that you downloaded and follow the prompts. If necessary, you can refer to the PostgreSQL installation instructions.
  3. Enter a password for the super user ('postgres'). Remember this username and password. You will need it each time you log in to the database.
  4. Accept the default port 5432.
  5. Accept all the other default settings.

Step 3. Optional: Create your JIRA Database in PostgreSQL

Below are the instructions for creating a JIRA database in a PostgreSQL database server.

  • If your JIRA installation is already using a different supported database server and you have a good technical knowledge of that server, you can choose to stick with that server and skip this step.
  • If your JIRA installation is using the default HSQLDB, supplied with JIRA for evaluation purposes, you will need to migrate to another database before using JIRA in a production environment. Please follow the instructions on migrating your JIRA data to an external database.

Now you will create a database where the Atlassian JIRA application will store its data, and the user that JIRA will use to connect to the database. We are assuming that you have already created your PostgreSQL database server in a previous step.

(info) We are using pgAdmin III, the administration user interface supplied with PostgreSQL. If you used the one-click installer when installing PostgreSQL, pgAdmin III will be already installed on your computer.

  1. Start pgAdmin III.
  2. Right-click (or double-click) the database server name and log in using the password that you specified for the 'postgres' super user.
  3. Add a new login role called 'jirauser':
    • Right-click Login Roles and select New Login Role.
    • Enter the role Role name: jirauser
    • Enter a Password and enter it again to confirm it.
    • Click the Role privileges tab.
    • Select Can create database objects.
    • Select Can create roles.
    • Click OK to create the user.
  4. Add a new database called 'jira':
    • Right-click Databases and select New Database.
    • Enter the database Name: jira
    • Select the Owner: jirauser
    • Click OK to create the database.

Alternatively, If you are on UNIX and do not have pgAdmin III, you can use the command line interface instead. Assuming that you are using the default installation directory of /opt/PostgreSQL/8.4/bin/, enter the following commands:

sudo -s -H -u postgres
# Create the JIRA user:
/opt/PostgreSQL/8.4/bin/createuser -S -d -r -P -E jirauser
# Create the JIRA database:
/opt/PostgreSQL/8.4/bin/createdb --owner jirauser --encoding utf8 jira
exit

Screenshot 1 (click to enlarge): JIRA database and user in PostgreSQL

Step 4. Upgrade JIRA If Necessary

Requirements: JIRA 5.0.

  1. Check your version of JIRA.
  2. If you do not have JIRA 5.0 or later, follow the instructions on upgrading to JIRA 5.0

Problems? Please raise a support ticket for the product you're stuck on, or see answers from the community.
Victory? Please continue.

Step 5. Configure JIRA Options

In this step you will enable some JIRA features that are required for the later stages in this integration procedure.

  1. Log in to JIRA with an administrator account.
  2. Create a new administrator account for Charlie of Atlassian:
    • Click Administration in JIRA's top navigation bar.
    • Choose Users > Users, then Add User.
    • The 'Add New User' screen will appear. Enter the following information:
      • Username: charlie
      • Password – Enter a password for the administrator account and enter it again to confirm it.
      • Full Name: Charlie of Atlassian
      • Email – We recommend that you give your own email address here.
      • Send Notification Email – Do not tick this checkbox.
    • Click Add.
    • Now you will add Charlie to the 'jira-administrators' group. Choose Users > Groups.
    • Click the jira-administrators group.
    • Click Edit Members.
    • Select charlie in the list under Join.
    • Click Join.
  3. Check JIRA's base URL:
    • Choose System > General Configuration.
    • Change the Base URL if necessary. It must contain the full website address at which JIRA is running, not just 'localhost'. For example, if your computer name is 'coopers' then the base URL should be: http://coopers:8080. Or specify a website address, such as http://www.foobar.com:8080.
  4. Check the following configurations and update them if necessary:
    1. Allow unassigned issues and check that the remote API is enabled:
      • Click Administration in the top navigation bar.
      • Click System > General Configuration in the top menu.
      • Enter your password as prompted, to confirm that you want administrator access. (Note that the Atlassian applications will request this confirmation at various steps in the process. This guide will not mention this step again.)
      • Click Edit Configuration.
      • Select the ON radio button next to Allow unassigned issues.
      • Check that the ON radio button is selected next to Accept remote API calls. It is on by default.
      • Click Update.
    2. Add the groups that you will need later for Confluence and Bamboo:
      • Click Users > Groups in the top menu.
      • In the Add Group section, enter a group name of 'confluence-users' and click Add Group.
      • Add the following two groups as well:
        • confluence-administrators
        • bamboo-admin
    3. Make Charlie of Atlassian  a user and administrator in Confluence and Bamboo by adding him to the relevant groups:
      • Click Bulk Edit Group Members.
      • In the left-hand box, select the three groups:
        • bamboo-admin
        • confluence-administrators
        • confluence-users
      • In the right-hand box under Add members to selected group(s), enter the username: charlie
      • Click Join. Charlie's name will appear in the middle box as a group member of the selected groups.

Problems? Please raise a support ticket for the product you're stuck on, or see answers from the community.
Victory? Please continue.

Step 6. Set up a Project and Create your JIRA Dashboard

In this step you will create some data in JIRA, including a project and an issue, for use in the subsequent stages of this integration procedure. Then you will create your own JIRA dashboard with a couple of gadgets.

  1. Create a project in JIRA:
    • Click Projects > Projects in the top menu.
      Hint: Try JIRA's quick search instead of the menus. Press g g on your keyboard then start typing 'projects' into the Administration Search box. If you like, you can use the quick search from this point onwards.
    • Click Add Project.
    • Enter the following information:
      • Name: Dragons
      • Key: DRA
    • Click Add.
  2. Add two versions (1.0 and 2.0):
    • Click Versions in the left-hand panel of the Dragons project screen.
    • Enter the following information then click Add:
      • Name: 1.0
      • Description: Version 1.0
    • Add Version 2.0 as well.
  3. Add an issue to your project:
    • Click Exit Administration at the top of the administration screen
    • The dashboard will appear. Click Create Issue at the top of the dashboard.
    • Enter the following information about your new issue:
      • Project: Dragons
      • Issue Type: Bug
      • Summary: Dragon slayer's equipment is defective
      • Affects Version/s: 1.0
      • Assignee – Click Assign To Me, so that the assignee is: Charlie of Atlassian
      • Description: There's a hole in the dragon slayer's water bucket
      • Original Estimate: 1d
    • Click Create. You now have an issue with a key of 'DRA-1'. Click the issue key and take a look at your new issue.
  4. Create a new dashboard for all your dragon-related tasks, issues and general fire fighting:
    • Click Dashboards at top left of your JIRA screen.
    • Click Tools > Create Dashboard.
    • The Create New Dashboard  screen will appear. Enter the following information:
      • Name: Dragon Development Dashboard
      • Description: A dashboard for dragon slayers, fire fighters and like-minded brave souls
    • Leave the other fields at their default values and click the Add button at the bottom of the 'Create New Dashboard' screen (not the one next to 'Add Shares').
  5. You now have a new, empty dashboard. Add the 'Projects' gadget to the dashboard:
    • Click Add Gadget.
    • The 'Gadget Directory' will appear, showing a list of the available gadgets for your JIRA dashboard. Enter 'projects' into the search box at top right of the gadget directory.
    • The list of gadgets will change, to show only the gadgets that match your search term. Find the 'Projects' gadget and click Add it Now. The gadget will be highlighted for a short time and the button's wording will change to 'Adding', while JIRA adds the gadget to the dashboard.
  6. Find and add the 'Assigned To Me' gadget in the same way.
  7. Click Finished to go back to your dashboard.
  8. Drag the 'Assigned to Me' gadget to the top right of your dashboard:
    • Move your mouse pointer over the gadget's blue title bar.
    • The cursor icon will change to a four-pointed arrow (or a hand). Click the gadget title bar with the left mouse button then drag the gadget to the right. Drop it in the space labelled 'Drag your gadget here.'
  9. Configure the 'Assigned to Me' gadget to point to your 'Dragons' project:
    • Leave the default values as configured for Number of Results and Columns to display.
    • Click the dropdown arrow next to Refresh Interval and select Every 15 Minutes.
    • Click Save.
  10. Configure the 'Projects' gadget:
    • Leave the default values as configured for Projects, View and Number of Columns.
    • Click the dropdown arrow next to Refresh Interval and select Every 15 Minutes.
    • Click Save.
Problems? Please raise a support ticket for the product you're stuck on, or see answers from the community.
Victory? Please continue.

Victory!

(tick) You can now see your project dashboard with 2 gadgets on it! The 'Projects' gadget shows the project lead Charlie of Atlassian. The 'Assigned to Me' gadget shows the single DRA-1 issue assigned to Charlie.

Screenshot 3 (click to enlarge): JIRA dashboard with 2 gadgets

Problems? Please raise a support ticket for the product you're stuck on, or see answers from the community.
Victory? Please continue.

Take a Bow and Move to the Next Stage