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 and add a dynamic display of JIRA issues to a wiki page.

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 database 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
    • Click the Definition tab
    • Enter a Password and enter it again to confirm it.
    • Click the Role privileges tab.
    • Select Can create databases.
    • 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 5.7.1.

  1. Go to the Atlassian download centre.
  2. Download the Confluence 5.7.1 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 5.7.1, click downloads archive and get Confluence 5.7.1.
    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 5.7.1.
    • If you are running 32-bit Windows, download the Windows Installer (32 Bit) file for Confluence 5.7.1.
  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]. (If this doesn't work, use service.msc to start Confluence.)
  11. The next step is to open the Confluence Setup Wizard in your web browser. See below for instructions.
  1. Go to the Atlassian download centre.
  2. Click the Linux tab and download the Confluence 5.7.1 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 5.7.1, click downloads archive and get Confluence 5.7.1.
    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 5.7.1 and continue following the installation steps below.
    • If you are running 32-bit Linux, download the Linux Installer (32 Bit) file for Confluence 5.7.1 and continue following the installation steps below.
    • If you are running some other flavor of UNIX, download the Standalone (TAR.GZ Archive) file for Confluence 5.7.1 and follow the Confluence guide to installing from an archive through the end of Step 4, then return here and skip to part 8, Start your Confluence Server.
  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. During the installation, take note of the directory where the Confluence installation files are saved (this is called the 'destination directory'). You will need to reference this directory later.
  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 'Installation 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. Click Start setup under 'Production Installation'.
  4. Enter your Confluence license into the License Key field. If you do not already have a Confluence license, click the generate an evaluation license online link and follow the prompts.
  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.
    Note: The Next button may appear greyed out, preventing progress to the next stage. A workaround is available in CONF-23184.
    The 'Confluence Setup Successful' screen will appear. Click Start using Confluence.
  11. If the 'What's new in Confluence' popup window appears, select Don't show again and click Close.
  12. The home page of the Confluence 'Demonstration Space' will appear.
  13. Finally, you need to change your Confluence base URL to the full web address at which Confluence is running, and enable the remote API:
    • Click  > General Configuration. Confirm your password when prompted. This is Charlie's password in Confluence, and is the same as his password in JIRA.
    • 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.
    • Click Further Configuration under 'Configuration' in the left-hand panel.
    • The 'Further Configuration' screen will appear. Click any of the Edit links.
    • Click the check box next to Remote API (XML-RPC & SOAP), to enable the remote API.
    • Scroll down to the end of the page and click Save.
  14. If you changed the server base URL, then logout and login again using the new base URL.

Screenshot 2 (click to enlarge): Confluence Home page

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 Confluence at the top left of the Confluence screen.
  2. Click Create Space in the Spaces menu. The 'Create Space' screen will appear.
  3. Click Create and choose Blank Space.
  4. Configure your space settings:
    • Enter a space name: Dragons
    • Enter a space key: DRA
    • Click Create.
  5. 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, so you can start with an empty page. You will need to delete the text from each section.
    • Make sure your cursor is at the top of the editor pane.
    • Choose insert more button > Files and images 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 more button > JIRA Issue/Filter in the editor toolbar.
    • The 'Insert JIRA Issue/Filter' popup window will appear.
    • Enter the following JQL (JIRA Query Language) phrase into the search box: project = DRA
    • Click the search button button.
    • A list of issues will appear, matching your search query. 
    • Click Insert.

    • The JIRA macro will appear on your page.

  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 and start a new line.
  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 more button > JIRA Issue/Filter in the editor toolbar.
    • The 'Insert JIRA Issue/Filter' popup window will appear. Click Create New Issue in the left-hand panel.
    • Enter the following information:
      • Project: Dragons (DRA)
      • Issue Type: Bug
      • Summary: The purple dragon melted my chocolate
      • Description: The dragon tried to eat my chocolate and flamed it by mistake
    • Click Insert.

    • You now have a new issue, DRA-2, in the Dragons project 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-2. The Issue Links section includes a link to the wiki page.
    While you are looking at the issue, click Assign to me to assign it to yourself .

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

updated confluence home page

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

Victory!

Your Confluence page has a dynamic list of JIRA issues.

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
  • No labels