This page last changed on Jun 22, 2011 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 activity stream 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.
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.
- Start pgAdmin III.
- 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.
- 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.3/bin/, enter the following commands:
Screenshot 1 (click to enlarge): Confluence database and user in PostgreSQL

Step 2. Install Confluence
Requirements: Confluence 3.5.5.
For Windows: (click to expand)
- Go to the Atlassian download centre.
- Download the 'Standalone (ZIP Archive)' file for Confluence 3.5.5.
Do not use the 'Windows Installer' for this integration exercise, because the workflow for configuring an external database is simpler when installing from the zip archive. If you cannot see the 'Zip Archive', click the 'Show all' link above the download buttons to see all the download file types.
Please use the Confluence version specified in this documentation. If the download centre shows a Confluence version later than 3.5.5, click 'downloads archive' and get Confluence 3.5.5.
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.
- Unpack the zip archive into a directory of your choice, avoiding spaces in the directory name.
- Tell Confluence where to put its Confluence Home directory:
- Edit the properties file at {CONFLUENCE_INSTALL}\confluence\WEB-INF\classes\confluence-init.properties.
- Remove the hash sign (#) in front of the following line, and enter the directory name:
# confluence.home=c:/confluence/data
For example:
confluence.home=c:/data/confluence-home
(Note the forward slashes.)
- Save the file.
- Because Confluence will be running on the same machine as JIRA (already installed), you need to ensure that the ports and URL paths are different for Confluence and JIRA. By default, both applications use port 8080. Change the default Confluence port and path as follows:
- Edit the configuration file at {CONFLUENCE_INSTALL}\conf\server.xml.
- Change the value of the port attribute in the Connector element to 8090.
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8090" minProcessors="5"
maxProcessors="75"
enableLookups="false" redirectPort="8443" acceptCount="10" debug="0" connectionTimeout="20000"
useURIValidationHack="false" URIEncoding="UTF-8"/>
- Change the value of the path attribute in the Context element to /confluence:
<Context path="/confluence" docBase="../confluence" debug="0" reloadable="false" useHttpOnly="true">
- Start your Confluence server by running {CONFLUENCE_INSTALL}\bin\startup.bat.
For UNIX or Linux: (click to expand)
- Go to the Atlassian download centre.
- Click the 'Linux' tab and download the 'Standalone (TAR.GZ Archive)' file for Confluence 3.5.5.
Please use the Confluence version specified in this documentation. If the download centre shows a Confluence version later than 3.5.5, click 'downloads archive' and get Confluence 3.5.5.
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.
- Unpack the tar.gz archive into a directory of your choice, avoiding spaces in the directory name.
- Tell Confluence where to put its Confluence Home directory:
- Edit the properties file at {CONFLUENCE_INSTALL}/confluence/WEB-INF/classes/confluence-init.properties.
- Remove the hash sign (#) in front of the following line, and enter the directory name:
# confluence.home=c:/confluence/data
For example:
confluence.home=/var/confluence-home
- Save the file.
- Because Confluence will be running on the same machine as JIRA (already installed), you need to ensure that the ports and URL paths are different for Confluence and JIRA. By default, both applications use port 8080. Change the default Confluence port and path as follows:
- Edit the configuration file at {CONFLUENCE_INSTALL}/conf/server.xml.
- Change the value of the port attribute in the Connector element to 8090.
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8090" minProcessors="5"
maxProcessors="75"
enableLookups="false" redirectPort="8443" acceptCount="10" debug="0" connectionTimeout="20000"
useURIValidationHack="false" URIEncoding="UTF-8"/>
- Change the value of the path attribute in the Context element to /confluence:
<Context path="/confluence" docBase="../confluence" debug="0" reloadable="false" useHttpOnly="true">
- Start your Confluence server by running {CONFLUENCE_INSTALL}/bin/startup.sh.
Problems? Please raise a support ticket for the product you're stuck on, see answers from the community, or search the forum of past dragon slayers.
Victory? Please continue.
Step 3. Set Up Confluence
Now you can run Confluence's Setup Wizard and change some configuration settings.
- To access Confluence, go to your web browser and type this address: http://localhost:8090/confluence.
- 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.
- 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.
- Click 'Production Installation' under 'Choose Installation Type'.
- 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.
- On the 'Load Content' screen, click the 'Example Site' button to include the demonstration space content into your Confluence installation:.
- The 'Setup System Administrator' screen will appear. Enter the following information:
- Username: charlie
- Password – Enter a password for the administrator account and enter it again in the 'Confirm' field to confirm it.
- Name: Charlie of Atlassian
- Email – We recommend that you give your own email address here.
- Click the 'Next' button.
- The 'Confluence Setup Successful' screen will appear. Click 'Start using Confluence now'.
- If the 'What's new in Confluence' popup window appears, select 'Don't show again' and click 'Close'.
- The home page of the Confluence 'Demonstration Space' will appear.
- Finally, you need to change your Confluence base URL to the full (website) 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.
- 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 the 'Save' button.
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, see answers from the community, or search the forum of past dragon slayers.
Victory? Please continue.
Step 4. Hook Confluence up to JIRA for User Management
When you have finished setting up your Atlassian application suite, JIRA will hold all your users and groups and you will have a single username across all your Atlassian applications. In this step you will configure Confluence to use JIRA for centralised user management. To do that, you will define the Confluence application in JIRA, and define the JIRA user directory in Confluence.
- If JIRA is not already running, start it up by running {JIRA_INSTALL}\bin\startup.bat (Windows) or {JIRA_INSTALL}/bin/startup.bat (UNIX).
- Define the Confluence application to JIRA:
- Go to your JIRA URL in your browser, e.g. http://www.foobar.com:8080.
- Log in to JIRA with username charlie.
- Click 'Administration' in the top navigation bar.
- Click 'Other Applications' in the 'Users, Groups & Roles' section of the left-hand panel.
- Click 'Add Application'.
- The 'Add Application' screen will appear. Enter the following information:
- Application name: confluence
- Password – Enter a password that Confluence will use to access JIRA.
- IP Addresses – On a new line, add the IP address or addresses of your Confluence server. For example: 192.168.10.12.
Also add this IP address: 127.0.1.1
- Click 'Save'.
- Set up the JIRA user directory in Confluence:
- Log out of Confluence, but leave Confluence running.
- Log in to Confluence again, with the same username charlie and Charlie's password in JIRA.
You are now authenticating via JIRA!
Screenshot 3 (click to enlarge): Confluence user directories
Full details are in the Confluence administrator's guide.
Problems? Please raise a support ticket for the product you're stuck on, see answers from the community, or search the forum of past dragon slayers.
Victory? Please continue.
Step 5. Get JIRA and Confluence Talking
In this step you will set up the trusted communication channel between your JIRA and Confluence sites, so that you can display JIRA information on Confluence pages and Confluence information on the JIRA dashboard. This will be a two-way trust relationship: Confluence will trust JIRA and JIRA will trust Confluence. You will also make your Confluence gadgets available in JIRA.
- Make sure that both JIRA and Confluence are running.
- Go to your Confluence URL in your browser, e.g. http://www.foobar.com:8090/confluence.
- Select 'Application Links' from the 'Administration' section of the Confluence Administration Console.
- The 'Configure Application Links' screen will appear. Click 'Add Application Link'.
- The first screen of the 'Add Application Link' wizard will appear. Copy the base URL for your JIRA site (e.g. http://coopers:8080 or http://www.foobar.com:8080) and paste it into the 'Server URL' field.
- Click 'Next'.
- The 'Link to JIRA' screen will appear. Enter the following information:
- Create a link back to this server – This option is selected by default. Let it remain selected.
- Username: charlie. This is the username of the administrator on your JIRA site.
- Password – Enter Charlie's password in JIRA.
- Reciprocal Link URL – Leave this field at its default value, pointing to your Confluence site.
- Click 'Next'.
- The 'Set Users and Trust' screen will appear. Enter the following information:
- The servers have the same set of users – This option is selected by default. Let it remain selected.
- These servers fully trust each other – This option is selected by default. Let it remain selected.
- Click 'Create'.
- Now you will make your Confluence gadgets available in JIRA, so that JIRA users will be able to add any Confluence gadget to their dashboards. Go to your JIRA browser window and click 'Dashboards' in JIRA's top navigation bar.
- Click 'Add Gadget'.
- The 'Gadget Directory' popup window will appear. Click 'Gadget Subscriptions'.
- The 'Gadget Subscriptions' popup window will appear. Click 'Add Subscription'.
- 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.
- Click 'Add Subscription'.
- Click 'Finished'.
The Confluence gadgets are now available in your JIRA gadget directory. You have not yet added them to your JIRA dashboard. We will do that in a later step.
Screenshot 4 (click to enlarge): Adding JIRA as a trusted application in Confluence
The Confluence documentation has the details about application links and trusted applications.
Problems? Please raise a support ticket for the product you're stuck on, see answers from the community, or search the forum of past dragon slayers.
Victory? Please continue.
Step 6. 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.
The Atlassian Confluence demonstration space was created for you when you set up Confluence above.
- Click 'Dashboard' at the top left of the Confluence screen.
- Click 'Add Space' on the left-hand side of the screen.
- 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'.
- 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 rich text 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.
- Click the 'Insert Image' icon
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. Alternatively, you can drag and drop the image from your desktop into the 'Insert Image' window.
- The image will appear in the preview panel of 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, see answers from the community, or search the forum of past dragon slayers.
Victory? Please continue.
Step 7. 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.
- Edit the Confluence page again.
- Place your cursor immediately after your Charlie badge image and press 'Enter' to start a new line.
- Enter the following text onto the page: My JIRA issues.
- 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'.)
- Deselect the text and then press 'Enter' to start a new line.
- Follow the steps below to add a JIRA macro to your page, showing a dynamic list of issues drawn from the 'Dragons' project on your JIRA site.
- Click the 'Insert JIRA Issue' icon
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) 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:
{jira:project = DRA|server=Your Company JIRA}
- Click the 'Preview' tab to see a preview of the page. You will see a list of the JIRA issues in your 'Dragons' project.
- Click the 'Rich Text' tab to return to the editor.
- Enter the following text onto the page, and format it as a heading level 2: Reporting a new issue.
- Start a new line.
- Follow the steps below to add a new issue into JIRA and display the issue on your Confluence page:
- Click the 'Insert JIRA Issue' icon
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-4 in JIRA. In addition, a new JIRA macro will appear on your Confluence page, showing only the issue that you have created in JIRA. In edit mode the macro looks like this:
{jira:DRA-4|server=Your Company JIRA}
- Save the page.
Note: The new issue will appear immediately under the heading 'Reporting a new issue'. You may need to click the refresh icon at the bottom of the table of issues, to see the new issue appear in the table. This is because the issues shown in the table are cached.
Screenshot 5 (click to enlarge): Your updated Dragons home page in Confluence

Problems? Please raise a support ticket for the product you're stuck on, see answers from the community, or search the forum of past dragon slayers.
Victory? Please continue.
Step 8. Add a Confluence Gadget to JIRA
Now you will add the Confluence 'Activity Stream' gadget to your JIRA Dragon Development Dashboard.
- Click 'Dashboards' at top left of your JIRA screen.
- Your 'Dragon Development Dashboard' will appear. Click 'Add Gadget'.
- The 'Gadget Directory' will appear, showing a list of the available gadgets for your JIRA dashboard. Enter 'activity' 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. You will see two 'Activity Stream' gadgets, once for JIRA and one for Confluence. To find the Confluence one, look at the gadget URL and find the URL that contains port '8090'.
- Click 'Add it Now' under the appropriate 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.
- Click 'Finished' to go back to your dashboard.
- Configure the 'Activity Stream' gadget:
- Enter 'Confluence Dragons Activity' in the 'Title' field.
- Select 'Dragons' in the 'Projects' field.
- Click the dropdown arrow next to 'Refresh Interval' and select 'Every 15 Minutes'.
- Leave the other fields at their default values and click 'Save'.
- Re-arrange your 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.
- Choose a different colour for your 'Activity Stream' 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, see answers from the community, or search the forum of past dragon slayers.
Victory? Please continue.
Victory!
Your JIRA dashboard now has 4 gadgets:
- The Confluence 'Activity Stream' gadget
- The 'Assigned to Me' gadget
- The 'Projects' gadget
- The GreenHopper 'Agile Gadget'
Screenshot 6 (click to enlarge): JIRA dashboard with 4 gadgets

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

|
Grab your Sword and Move to the Next Stage
|
|