Atlassian Integration Guide : Dragons with JIRA Stage 2 - Set Up JIRA
This page last changed on Dec 09, 2010 by alui.


Beware of fiends and dragons on the gargoyled eaves. You are embarking on stage 2 of the Atlassian Dragon Quest.

In this stage, you will configure Atlassian JIRA for bug tracking and issue management. You will also hook JIRA up to Crowd, for SSO and centralised user management.

Time estimate: This stage will take approximately 60 minutes.

On this page:

Step 1. 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 Dragons Stage 1.

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. 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.
    • Select 'Can create database objects'.
    • Select 'Can create roles'.
    • Click 'OK' to create the user.
  3. 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 -O jirauser jira
exit

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

Step 2. Upgrade JIRA If Necessary

Requirements: JIRA 4.2.

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

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Step 3. 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.
    • The 'Projects' administration screen will appear. Click 'User Browser' in the left-hand panel.
    • The 'User Browser' screen will appear. Click 'Add User'.
    • The 'Create 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 address – We recommend that you give your own email address here.
    • Click 'Create'.
    • Now you will add Charlie to the 'jira-administrators' group. Click 'Group Browser' in the left-hand panel.
    • Click the 'jira-administrators' group.
    • Click 'Edit Members'.
    • Select 'charlie' in the list under 'Join'.
    • Click 'Join'.
  3. Check JIRA's base URL:
    • Click 'General Configuration' in the left-hand panel.
    • 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. Turn on the public API and allow unassigned issues:
      • Click 'General Configuration' in the left-hand panel (in the 'Global Settings' section).
      • Click 'Edit Configuration'.
      • Select the 'ON' radio button next to 'Allow unassigned issues'.
      • Select the 'ON' radio button next to 'Accept remote API calls'.
      • Click 'Update'.
  5. Log out of JIRA, but leave JIRA running. (Click the dropdown arrow next to the name 'Charlie of Atlassian', then select 'Log Out'.)

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Step 4. Import your JIRA Users into Crowd

In this step you will import your existing JIRA users and groups into Crowd.

For the purposes of this integration exercise, we assume that you currently have your users and groups defined in JIRA. If you are using LDAP, please do the following:

  1. Ensure that the database drivers for your JIRA database are on Crowd's classpath:
    • If you are using the PostgreSQL database described in step 1 above, then the database drivers are already in Crowd. There is no need to do anything here.
    • If you are using a different database server, copy the JDBC driver JAR for your particular JIRA database across to your Crowd installation directory:
      • In Windows: {CROWD_INSTALL}\apache-tomcat\common\lib
      • In UNIX: {CROWD_INSTALL}/apache-tomcat/common/lib
    • Restart Crowd.
  2. If Crowd is not already running, start it up by running {CROWD_INSTALL}\start_crowd.bat (on Windows) or {CROWD_INSTALL}/start_crowd.sh (on UNIX).
  3. Go to your Crowd URL in your browser, e.g. http://www.foobar.com:8095/crowd.
  4. Log in to Crowd with username charlie.
  5. Click 'Users' in Crowd's top navigation bar.
  6. The 'User Browser' will appear. Click 'Import Users'.
  7. The 'Import Type' screen will appear. Click 'Atlassian Importer'.
  8. The 'Options' screen will appear. Enter the following information:
    • Atlassian Product: JIRA.
    • Directory: Crowd
    • Import Passwords – Select this checkbox.
    • Product Database URL – Enter the URL of your JIRA instance's database. The exact syntax will depend on your database server. If you are using the PostgreSQL database described in step 1 above, then the value will be: jdbc:postgresql://localhost:5432/jira.
    • Database Driver – Enter the class name of your JIRA JDBC driver. If you are using the PostgreSQL database described in step 1 above, then the value will be: org.postgresql.Driver.
    • Username – Enter the username that Crowd will use to access your JIRA database. If you are using the PostgreSQL database described in step 1 above, then the value will be: jirauser
    • Password – Enter the password of the above database user.
  9. Click 'Continue' to import the users from your JIRA installation into your Crowd directory.
  10. The 'Results' screen will show how many users and groups have been imported into your Crowd directory.

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Step 5. Hook JIRA up to Crowd

In this step you will define the JIRA application in Crowd and configure JIRA to use Crowd for SSO and centralised user management.

  1. If Crowd is not already running, start it up by running {CROWD_INSTALL}\start_crowd.bat (on Windows) or {CROWD_INSTALL}/start_crowd.sh (on UNIX).
  2. Go to your Crowd URL in your browser, e.g. http://www.foobar.com:8095/crowd.
  3. Log in to Crowd with username charlie.
  4. Click 'Applications' in the top navigation bar.
  5. The 'Application Browser' will appear. Click 'Add Application' in the left-hand menu.
  6. This will display the first screen for the 'Add Application' wizard for Crowd. Enter the following information:
    • Application Type: JIRA.
    • Name: jira.
    • Description: Atlassian JIRA.
    • Password – Enter the password that JIRA will use to access Crowd and enter it again to confirm it.
    • URL – Enter the base URL of your JIRA site, e.g. http://www.foobar.com:8080.
    • Click 'Resolve IP Address' to ask Crowd to find the 'Remote IP Address' for you. The value will be something like this: 127.0.0.1.
    • Select the 'Crowd' directory.
    • Select 'Allow all users to authenticate'.
    • Click 'Add Application'.
  7. Check the IP addresses for your JIRA application:
    • Click the 'Remote Addresses' tab.
    • Add your JIRA host name, excluding the "http://www." prefix and the ":8080" port number. e.g. foobar.com.
    • If it's not already present, add: 127.0.0.1.
  8. Leave Crowd up and running, but shut down JIRA. (Press Ctrl+C in your JIRA server command window or run {JIRA_INSTALL}\bin\shutdown.bat (on Windows) or {JIRA_INSTALL}/bin/shutdown.sh (on UNIX).)
  9. Copy the Crowd configuration files to your JIRA installation folder:
    • Copy {CROWD_INSTALL}/client/conf/crowd.properties
      to {JIRA_INSTALL}/atlassian-jira/WEB-INF/classes.
    • Copy {CROWD_INSTALL}/client/conf/crowd-ehcache.xml
      to {JIRA_INSTALL}/atlassian-jira/WEB-INF/classes.
  10. Edit the {JIRA_INSTALL}/atlassian-jira/WEB-INF/classes/crowd.properties file and change the following properties:
    • application.name: jira
    • application.password – Enter the password that JIRA will use to access Crowd. This must be the same password as you entered in the Crowd 'Add Application' wizard above.
  11. Edit the {JIRA_INSTALL}/atlassian-jira/WEB-INF/classes/osuser.xml file. Comment out any existing authentication providers and uncomment the Crowd providers, as instructed in the text of the file itself.
  12. Edit the {JIRA_INSTALL}/atlassian-jira/WEB-INF/classes/seraph-config.xml file. Comment out the 'JiraOsUserAuthenticator' class and uncomment the 'JIRAAuthenticator' class, as instructed in the text of the file itself.
  13. Start your JIRA server again, and go to your JIRA URL in your browser, e.g. http://www.foobar.com:8080.
  14. Log in to JIRA with username charlie and Charlie's password in Crowd.
    You are now authenticating via Crowd!
  15. Turn on external user management in JIRA, so that all user management happens in Crowd rather than JIRA:
    • Click 'Administration' in the top navigation bar.
    • Click 'General Configuration' in the left-hand panel (in the 'Global Settings' section).
    • Click 'Edit Configuration'.
    • Change 'Mode' to 'Private'.
    • Select the 'ON' radio buttons next to 'External user management' and 'External password management'.
    • Click 'Update'.

Screenshot 3: The JIRA application defined in Crowd – 'Remote Addresses' tab

Full details are in the Crowd documentation.

The default JIRA groups are: jira-administrators, jira-developers and jira-users.
If your JIRA installation includes additional groups, over and above the default three, you will need to give the imported groups access to the JIRA application in Crowd. See Specifying which Groups can access an Application.

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
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 'Administration' in the top navigation bar.
    • Click 'Projects' in the left-hand panel, then click 'Add Project'.
    • Enter the following information:
      • Name: Dragons.
      • Key: DRA.
      • Project Lead: charlie.
      • Description: Atlassian Dragon Quest.
    • Leave the rest of the fields with their default values. Click 'Add'.
  2. Add two versions (1.0 and 2.0):
    • Click 'Manage versions'.
    • Enter the following information then click 'Add':
      • Version Name: 1.0.
      • Description: Version 1.0.
    • Follow the same steps to add Version 2.0.
  3. Add an issue to your project:
    • Click 'Create Issue' at top right of the screen, select the following options then click 'Create':
      • Project: Dragons.
      • Issue Type: Bug.
    • Enter the following information about your new issue then click 'Create':
      • Summary: Dragon slayer's equipment is defective
      • Affects Version/s: 1.0.
      • Assignee: Charlie of Atlassian – Click 'Assign to me'.
      • Description: There's a hole in the dragon slayer's water bucket.
      • Original Estimate: 1d.
    • You now have an issue with a key of 'DRA-1'.
  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' at top right of the screen, then '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 screen.
    • 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. 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:
    • Refresh the dashboard, if necessary, to show the 'Number of Results' and other configuration fields in the gadget.
    • 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 try the Dragon Slayers' Forum.
Victory? Please continue.

Victory!

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 4 (click to enlarge): JIRA dashboard with 2 gadgets

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.
Take a Bow and Move to the Next Stage
Document generated by Confluence on Feb 27, 2011 17:37