Atlassian Integration Guide : Dragons Stage 3 - Install Confluence

This page last changed on Mar 28, 2012 by smaddox.


Beware of low-flying worms. You are embarking on stage 3 of the Atlassian Dragon Quest.

In this stage, you will install Atlassian Confluence, the enterprise wiki. You will configure JIRA to manage your Confluence users, and get your JIRA and Confluence sites talking to each other. Then you will create a wiki space, add a dynamic display of JIRA issues to a wiki page, and add a Confluence gadget to your JIRA dashboard.

Time estimate: This stage will take approximately 60 minutes.

On this page:

Step 1. Create your Confluence Database in PostgreSQL

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

(info) We are using pgAdmin III, the administration user interface supplied with PostgreSQL. If you used the one-click installer in Dragons Stage 1, 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 'confuser':
    • Right-click Login Roles and select New Login Role.
    • Enter the Role name: confuser
    • 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 'confluence':
    • Right-click Databases and select New Database.
    • Enter the database Name: confluence
    • Select the Owner: confuser
    • 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 Confluence user:
/opt/PostgreSQL/8.4/bin/createuser -S -d -r -P -E confuser
# Create the Confluence database:
/opt/PostgreSQL/8.4/bin/createdb --owner confuser --encoding utf8 confluence
exit

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

Step 2. Install Confluence

Requirements: Confluence 4.1.6.

For Windows: (click to expand)
  1. Go to the Atlassian download centre.
  2. Download the Confluence 4.1.6 installer for your Windows system.
    (warning) Please use the Confluence version specified in this documentation. If the download centre shows a Confluence version later than 4.1.6, click downloads archive and get Confluence 4.1.6.
    Why?  We have tested the integration suite with this version. There is a chance that you will have problems integrating the other applications if you use a different version.
    • If you are running 64-bit Windows, download the Windows Installer (64 Bit) file for Confluence 4.1.6.
    • If you are running 32-bit Windows, download the Windows Installer (32 Bit) file for Confluence 4.1.6.
  3. Log in to your computer as a Windows administrator.
    To install Confluence as a service, you must run the Windows installer using a Windows administrator account. While you can run the Windows installer with a non-administrator account, your installation options will be limited.
  4. Run the Confluence installer .exe file.
    (warning) On Windows 7 or Vista, right-click the file name and click Run as administrator.
  5. If a Windows 7 or Vista 'User Account Control' dialog box asks you to allow the installation wizard to make changes to your computer, specify 'Yes'.
  6. Select Express Install as the installation option.
  7. The installer will display the 'Installation Summary'. Click Install to confirm that you want the default options.
  8. When prompted, click Finish. The installer will finish installing Confluence and start the Confluence server.
  9. Because Confluence will be running on the same machine as JIRA (already installed), you need to ensure that the URL paths are different for Confluence and JIRA. Change the default Confluence path as follows:
    • Stop the Confluence server: Go to your Windows Start menu and choose Confluence > Stop Confluence Service [8090].
    • Go to your Confluence 'destination directory'. This is the directory where the Confluence installation files are stored. For example, if you used the 'Express Install' as described in step 6 above then the destination directory is C:\Program Files\Atlassian\Confluence. Let's call this directory '{CONFLUENCE_INSTALLATION}'.
    • Edit the configuration file at {CONFLUENCE_INSTALLATION}\conf\server.xml.

    • Change the value of the path attribute in the Context element to /confluence:

      <Context path="/confluence" docBase="../confluence" debug="0" reloadable="false" useHttpOnly="true">
    • Save the file.
      If Windows tells you that the file may be in use by another program, check whether you have stopped the Confluence server, as described above. If the server is stopped, then the problem is one of permissions. To get round the problem, copy the file to another directory and save the changes. Delete the file from the {CONFLUENCE_INSTALLATION}\conf directory and copy the updated version back into that directory.
  10. Start your Confluence server: Go to your Windows Start menu and choose Confluence > Start Confluence Service [8090].
  11. The next step is to open the Confluence Setup Wizard in your web browser. See below for instructions.
For UNIX or Linux: (click to expand)
  1. Go to the Atlassian download centre.
  2. Click the Linux tab and download the Confluence 4.1.6 installer for your UNIX system.
    (warning) Please use the Confluence version specified in this documentation. If the download centre shows a Confluence version later than 4.1.6, click downloads archive and get Confluence 4.1.6.
    Why?  We have tested the integration suite with this version. There is a chance that you will have problems integrating the other applications if you use a different version.
    • If you are running 64-bit Linux, download the Linux Installer (64 Bit) file for Confluence 4.1.6 and continue following the installation steps below.
    • If you are running 32-bit Linux, download the Linux Installer (32 Bit) file for Confluence 4.1.6 and continue following the installation steps below.
    • If you are running some other flavour of UNIX, download the Standalone (TAR.GZ Archive) file for Confluence 4.1.6 and follow the Confluence guide to installing from an archive then return to step 3 (Set Up Confluence) below.
  3. Open a Linux console and change directory (cd) to the directory containing the .bin file.
    If the .bin file is not executable after downloading it, make it executable. For example:
    chmod a+x atlassian-confluence-X.Y.bin
    (where X.Y represents your version of Confluence)
  4. Execute the .bin file with root user privileges, to start the Confluence installer.
    If you execute the installer with root user privileges, the installer will create and run Confluence using a dedicated user account. You can also execute the installer without root user privileges, but your installation options will be limited. To run Confluence as a service, you must execute the installer with root user privileges.
  5. Select Express Install as the installation option.
  6. The installer will finish installing Confluence and start the Confluence server.
  7. Because Confluence will be running on the same machine as JIRA (already installed), you need to ensure that the URL paths are different for Confluence and JIRA. Change the default Confluence path as follows:
    • Go to your Confluence 'destination directory'. This is the directory where the Confluence installation files are stored. Let's call this directory '{CONFLUENCE_INSTALLATION}'.
    • Stop your Confluence server by running {CONFLUENCE_INSTALLATION}/bin/stop-confluence.sh.
    • Edit the configuration file at {CONFLUENCE_INSTALLATION}/conf/server.xml.

    • Change the value of the path attribute in the Context element to /confluence:

      <Context path="/confluence" docBase="../confluence" debug="0" reloadable="false" useHttpOnly="true">
    • Save the file.
  8. Start your Confluence server by running {CONFLUENCE_INSTALLATION}/bin/start-confluence.sh.
  9. The next step is to open the Confluence Setup Wizard in your web browser. See below for instructions.

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

Step 3. Set Up Confluence

Now you can run Confluence's Setup Wizard and change some configuration settings. As part of this process, you will connect Confluence to JIRA, so that you can manage all your users via JIRA and share information between JIRA and Confluence.

  1. To access Confluence, go to your web browser and type this address: http://localhost:8090/confluence.
  2. The Confluence Setup Wizard will start up, to guide you through the process of setting up your Confluence server and creating an administration user. Detailed instructions are in the Confluence documentation.
  3. Enter your Confluence license into the License Key field. If you do not already have a Confluence license, follow the prompts on the Setup Wizard screen to generate an evaluation license online.
  4. Click Production Installation under 'Choose Installation Type'.
  5. The 'Choose a Database Configuration' screen will appear. Connect Confluence to your PostgreSQL database:
    • In the 'External Database' section, ensure that PostgreSQL is selected and click the External Database button.
    • The 'Configure Database' screen will appear. Click the Direct JDBC button in the 'Direct JDBC Connection' section.
    • Enter the following information:
      • Driver Class Name: org.postgresql.Driver – This is the default value.
      • Database URL: jdbc:postgresql://localhost:5432/confluence – This is the default value.
      • Username: confuser – This is the user you created in step 1 (above).
      • Password – Enter the password that you chose in step 1 (above).
    • Click the Next button. You might need to wait a few minutes while Confluence sets up its database.
  6. On the 'Load Content' screen, click the Example Site button to include the demonstration space content into your Confluence installation:.
  7. The 'User Management Setup' screen will appear. Click Connect to JIRA.
  8. The 'Connect to JIRA' screen will appear. Enter the following information:
    • JIRA Server Location – Enter the web address of your JIRA server. For example: http://www.foobar.com:8080/
    • JIRA Administrator Login Username: charlie
      This is Charlie's username in JIRA.
    • Password – Enter Charlie's password for JIRA.
  9. Leave the other fields (the 'advanced options') at their default values and click Next.
  10. The 'Load users and groups from JIRA' screen will appear, informing you that Confluence has created an administrative account for Charlie, to match his JIRA account. Click Next.
  11. The 'Confluence Setup Successful' screen will appear. Click Start using Confluence now.
  12. If the 'What's new in Confluence' popup window appears, select Don't show again and click Close.
  13. The home page of the Confluence 'Demonstration Space' will appear.
  14. Finally, you need to change your Confluence base URL to the full web address at which Confluence is running, not just 'localhost':
    • Open the Browse menu at the top of the screen and select Confluence Admin. Confirm your password when prompted. This is Charlie's password in Confluence, and is the same as his password in JIRA.
    • The 'Administration Console' screen will appear. Click General Configuration under 'Configuration' in the left-hand panel.
    • The 'General Configuration' screen will appear. Click any of the Edit links.
    • In the Server Base Url field, enter the full website address at which Confluence is running. This address should not be 'localhost'. For example, if your computer name is 'coopers' then the server base URL should be: http://coopers:8090/confluence. Alternatively, specify a website address such as http://www.foobar.com:8090/confluence.
    • Scroll down to the end of the page and click Save.

Screenshot 2 (click to enlarge): Home page of the Confluence demo space

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

Step 4. Create a Wiki Space

Now you can create a space in Confluence. A 'space' is a logical collection of pages, comparable to a library. A space is configurable and managed independently within the wiki site. It is almost like a wiki within a wiki.
(info) The Atlassian Confluence demonstration space was created for you when you set up Confluence above.

  1. Click Dashboard at the top left of the Confluence screen.
  2. Click Add Space on the left-hand side of the screen.
  3. The 'Create Space' screen will appear. Configure your space settings:
    • Enter a space name: Dragons
    • Enter a space key: DRA
    • Who can use this space? – Leave the default settings as they are.
    • Choose Theme – Leave the default settings as they are (that is, Global Look and Feel).
    • Click OK.
  4. The 'Home' page of your new 'Dragons' space will appear, with some default content. Now you can edit the home page as you like. For this exercise, you will add a Charlie badge:
    • Right-click on the image of the Charlie badge at the bottom of this documentation page and save it to your desktop. The file name is 'dragon_badge03.png'.
    • Click Edit at the top right of your new Dragons home page in your own Confluence site.
    • The wiki editor will open. If prompted, allow Gears access to your site. This will allow you to drag and drop images and other attachments onto your wiki page.
    • Select and delete all the text in the editor pane. You will start with an empty page.
    • Make sure your cursor is at the top of the editor pane.
    • Choose Insert > Image in the editor toolbar.
    • The 'Insert Image' popup window will appear. Browse to your desktop and upload the Charlie badge image that you saved earlier.
    • A preview of the image will appear in the 'Insert Image' window. Click Insert.
    • The image will appear in the editor pane of your home page. Click Save to save your updated wiki page.

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

Step 5. Add Some JIRA Issues to your Confluence Page

Now you can put some interesting JIRA content into your page. What's more, you can insert an issue into JIRA directly from your Confluence page and then display the issue on the page.

  1. Edit the Confluence page again.
  2. Place your cursor immediately after your Charlie badge image and press Enter to start a new line.
  3. Enter the following text onto the page: My JIRA issues
  4. Select the text that you have just entered and format it as a heading level 2. (Click the formatting dropdown menu on the left-hand edge of the editor tool bar. By default it formats your text as 'Paragraph'. Select Heading 2.)
  5. Deselect the text and then press Enter to start a new line.
  6. Follow the steps below to add a JIRA macro to your page. The macro will show a dynamic list of issues drawn from the 'Dragons' project on your JIRA site.
    • Choose Insert > JIRA Issue in the editor toolbar.
    • The 'Insert JIRA Issue' popup window will appear. Click Search in the left-hand panel.
    • Enter the following JQL (JIRA Query Language) phrase into the search box: project = DRA
    • Click the Search button.
    • A list of issues will appear, matching your search query. Select the option to Insert all query results as a table.
    • Click Insert.

    • The JIRA macro will appear on your page. In edit mode it looks like this:

  7. Click Preview at the bottom of the editor pane, to see a preview of the page. You will see a list of the JIRA issues in your 'Dragons' project.
  8. Click Edit to return to the editor.
  9. Enter the following text onto the page, and format it as a heading level 2: Reporting a new issue
    Hint: Press Ctrl+2 or Cmd+2 as a keyboard shortcut to format a heading level 2. Click the question mark on the right of the editor toolbar to see all the keyboard shortcuts.
  10. Start a new line.
  11. Follow the steps below to add a new issue into JIRA and display the issue on your Confluence page:
    • Choose Insert > JIRA Issue in the editor toolbar.
    • The 'Insert JIRA Issue' popup window will appear. Click Create New Issue in the left-hand panel.
    • Enter the following information:
      • Project: Dragons
      • Issue Type: Bug
      • Summary: The purple dragon melted my chocolate
      • Version/s: 2.0.S2
      • Description: The dragon tried to eat my chocolate and flamed it by mistake
    • Click Insert.

    • You now have a new issue DRA-5 in JIRA. In addition, a new JIRA macro will appear on your Confluence page, showing only the new issue that you have created in JIRA.

  12. Save the page.
    Note: The new issue will appear immediately under the heading 'Reporting a new issue'. To see the new issue appear in the table under 'My JIRA issues', you may need to click the refresh icon at the bottom of the table. This is because the issues shown in the table are cached.
  13. JIRA knows about the link between the new JIRA issue and the Confluence page! Go to your JIRA URL in your browser (for example, http://www.foobar.com:8080/) and find issue 'DRA-5'. The Issue Links section includes a link to the wiki page.

Screenshot 3 (click to enlarge): Your updated Dragons home page in Confluence

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

Step 6. Make your Confluence Gadgets Available in JIRA

In this step you will make your Confluence gadgets available in JIRA, so that JIRA users will be able to add any Confluence gadget to their dashboards.

  1. Go to your JIRA dashboard.
  2. Click Add Gadget.
  3. The 'Gadget Directory' popup window will appear. Click Gadget Subscriptions.
  4. The 'Gadget Subscriptions' popup window will appear. Click Add Subscription.
  5. The 'Add Subscriptions' popup window will appear. Copy the base URL for your Confluence site (e.g. http://coopers:8090/confluence or http://www.foobar.com:8090/confluence) and paste it into the text box on the screen.
  6. Click Add Subscription.
  7. Click Finished.

Step 7. Add a Confluence Gadget to JIRA

Now you will add the 'Confluence QuickNav' gadget to your JIRA dashboard.

  1. Click Dashboards at top left of your JIRA screen.
  2. Your 'Dragon Development Dashboard' will appear. Click Add Gadget.
  3. The 'Gadget Directory' will appear, showing a list of the available gadgets for your JIRA dashboard. Click Confluence in the left-hand panel.
  4. The directory will limit the list to gadgets published by Confluence. Find the Confluence QuickNav gadget and click Add it Now under the gadget. 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.
  5. Click Finished to go back to your dashboard.
  6. Test the new gadget – type 'tutorial' in the Search textbox inside the Confluence QuickNav gadget.
  7. A list of page titles will appear in a dropdown list. Open one of them in a new tab, to see the Confluence page.
  8. Re-arrange your JIRA dashboard:
    • Drag the Projects gadget to the right and drop it under the 'Assigned to Me' gadget.
    • Drag the Agile Gadget to the bottom right.
  9. Choose a different colour for your Confluence QuickNav gadget:
    • Move your cursor pointer over the gadget and click the downward-pointing arrow at top right of the gadget frame.
    • Select the red square in the row of colours.

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

Victory!

Your JIRA dashboard now has 4 gadgets:

  • The 'Confluence QuickNav' gadget
  • The 'Assigned to Me' gadget
  • The 'Projects' gadget
  • The GreenHopper 'Agile Gadget'

Screenshot 4 (click to enlarge): JIRA dashboard with 4 gadgets

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


Grab your sword and move to the next stage

Attachments:

PGAdminConfluenceDB.png (image/png)
PGAdminConfluenceDB.png (image/png)
ConfluenceDemoSpace.png (image/png)
InsertImageIcon.png (image/png)
ConfluenceDragonSpace.png (image/png)
ConfluenceDragonSpace.png (image/png)
ConfluenceDragonSpace.png (image/png)
ConfluenceDragonSpace.png (image/png)
ConfluenceExternalGadgets.png (image/png)
JIRATrustedApp.png (image/png)
JIRATrustedApp.png (image/png)
ConfluenceDragonSpaceV2.png (image/png)
InsertMacroIcon.png (image/png)
ConfluenceDragonSpaceV2.png (image/png)
ConfluenceExternalGadgets.png (image/png)
JIRADashboardStage4.png (image/png)
ConfluenceExternalGadgets.png (image/png)
ConfluenceDragonSpaceV2.png (image/png)
ConfluenceDemoSpace.png (image/png)
ConfluenceDemoSpace.png (image/png)
ConfluenceDemoSpace.png (image/png)
ConfluenceDemoSpace.png (image/png)
ConfluenceDragonSpace.png (image/png)
ConfluenceExternalGadgets.png (image/png)
JIRADashboardStage4.png (image/png)
JIRATrustedApp.png (image/png)
JIRADashboardStage4.png (image/png)
JIRATrustedApp.png (image/png)
PGAdminConfluenceDB.png (image/png)
ConfluenceDemoSpace.png (image/png)
ConfluenceDragonSpace.png (image/png)
ConfluenceExternalGadgets.png (image/png)
ConfluenceDemoSpace-v5.png (image/png)
ConfluenceAppLinks.png (image/png)
ConfluenceExternalGadgets-v5.png (image/png)
ConfluenceHomePage.png (image/png)
JIRADashboardStage4-v5.png (image/png)
InsertJIRAIcon.png (image/png)
ConfluenceUserDirectories.png (image/png)
ConfluenceHomePage-v6.png (image/png)
JIRARefreshIcon.png (image/png)
ConfluenceHomePage-v7.png (image/png)
JIRADashboardStage4-v7.png (image/png)
JIRADashboardStage4-v7.png (image/png)
ConfluenceHomePage-v7.png (image/png)
JIRARefreshIcon.png (image/png)
ConfluenceHomePage-v6.png (image/png)
ConfluenceUserDirectories.png (image/png)
InsertJIRAIcon.png (image/png)
JIRADashboardStage4-v5.png (image/png)
ConfluenceHomePage.png (image/png)
ConfluenceExternalGadgets-v5.png (image/png)
ConfluenceAppLinks.png (image/png)
ConfluenceDemoSpace-v5.png (image/png)
ConfluenceExternalGadgets.png (image/png)
ConfluenceDragonSpace.png (image/png)
ConfluenceDemoSpace.png (image/png)
PGAdminConfluenceDB.png (image/png)
JIRATrustedApp.png (image/png)
JIRADashboardStage4.png (image/png)
ConfluenceDragonSpaceV2.png (image/png)
InsertMacroIcon.png (image/png)
InsertImageIcon.png (image/png)
ConfluenceDemoSpace-v5.png (image/png)
JIRAIssuesMacro.png (image/png)
ConfluenceHomePage-v7.png (image/png)
JIRADashboardStage4-v7.png (image/png)
ConfluenceHomePage-v7.png (image/png)