Dragons Stage 3 – Install Confluence

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.

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) pgAdmin 4 is not supplied with the installer, so you will need to download it separately and install it. I am using v4.21 for this. If you installed it during the JIRA Install for Stage 1, you should already have it.

  1. Start pgAdmin 4.
  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 Login.
    • 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

Step 2. Install Confluence

Requirements: Confluence 7.4.0

For Windows:

  1. Go to the Atlassian download centre.
  2. Download the Confluence 7.4.0 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 7.4.0, click downloads archive and get Confluence 7.4.0.
    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.
  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.

For Unix or Linux

  1. Go to the Atlassian download centre.
  2. Click the Linux tab and download the Confluence 7.4.0 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 7.4.0, click downloads archive and get Confluence 7.4.0.
    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.
  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.

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. Click Next on the Get apps page – we will cover this in Stage 4
  5. 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.
  6. The ‘Choose a Database Configuration’ screen will appear. Connect Confluence to your PostgreSQL database:
    • Select “My own database”, then Next
    • The ‘Set up your database’ screen will appear.
    • Enter the following information:
      • Database Type: PostgreSQL
      • Hostname: localhost
      • Port: 5432
      • Database name: confluence
      • Username: confuser – This is the user you created in step 1.
      • Password: Enter the password that you chose in step 1.
    • Click the Next button. You might need to wait a few minutes while Confluence sets up its database.
  7. On the ‘Load Content’ screen, click the Example Site button to include the demonstration space content into your Confluence installation.
  8. The ‘User Management Setup’ screen will appear. Click Connect to JIRA.
  9. 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://localhost:8080/
    • JIRA Administrator Login Username: charlie
      This is Charlie’s username in JIRA.
    • Password: Enter Charlie’s password for JIRA.
  10. Leave the other fields (the ‘advanced options’) at their default values and click Next.
  11. 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.
  12. Confluence will ask you to setup a space. Type in “Test” and click Continue
  13. The home page of the Confluence ‘Demonstration Space’ will appear.
  14. Finally, you need to 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.
    • 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.

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 Update to save your updated wiki page.

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. Start a new line.
  8. 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.
  9. Start a new line.
  10. 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.
  11. 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.
  12. 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 .

Victory!

Your Confluence page has a dynamic list of JIRA issues.

Go to Dragons Stage 4 – Install Team Calendars in Confluence.