Atlassian Integration Guide : Dragons Stage 4 - Install Confluence This page last changed on Apr 07, 2010 by smaddox. There will be much flapping of wings and breathing of fire. You are embarking on stage 4 of the Atlassian Dragon Quest. In this stage, you will install Atlassian Confluence, the enterprise wiki. You will hook Confluence up to Crowd for SSO and centralised user management, and get your JIRA and Confluence sites talking to each other. Then you will create a wiki space, add two dynamic displays 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 Step 2. Install Confluence Step 3. Set Up Confluence Step 4. Hook Confluence up to Crowd Step 5. Get JIRA and Confluence Talking Step 6. Create a Wiki Space Step 7. Add a JIRA Gadget and Macro to your Confluence Page Step 8. Add a Confluence Gadget to JIRA Victory! ## 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 'Role name': `confuser`. 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. 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:
    sudo -s -H -u postgres
    # Create the Confluence user:
    /opt/PostgreSQL/8.3/bin/createuser -S -d -r -P -E confuser
    # Create the Confluence database:
    /opt/PostgreSQL/8.3/bin/createdb -O confuser confluence
    exit
10. Screenshot 1 (click to enlarge): Confluence database and user in PostgreSQL ## Step 2. Install Confluence Requirements: Confluence 3.2. For Windows: (click to expand) Go to the Atlassian download centre. Download the 'Standalone for Production Usage (ZIP Archive)' file for Confluence 3.2. 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. 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 application server ports for Confluence and JIRA are different. By default, both applications use port 8080. Change the default Confluence port 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`. 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.2. 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 application server ports for Confluence and JIRA are different. By default, both applications use port 8080. Change the default Confluence port 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`. Start your Confluence server by running {`CONFLUENCE_INSTALL}/bin/startup.sh`. Problems? Please go immediately to the Dragon Slayers' Forum. 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. 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 get an evaluation license key. Connect Confluence to your PostgreSQL database: Click the 'Custom Installation' button. The 'Choose a Database Configuration' screen will appear. 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. In the 'Setup Standard Database' section, enter the following information: Driver Class Name: `org.postgresql.Driver` – This is the default value. Database URL: `jdbc:postgresql://localhost:5432/confluence` Username: `confuser` – This is the user you created in step 1 (above). Password – This is the password you chose in step 1 (above). Click the 'Next' button. On the 'Load Content' screen, click the 'Example Site' button to include the demonstration space content into your Confluence installation:. You might need to wait a few minutes while Confluence sets up its database and the demonstration space content. 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'. The 'Confluence Demonstration Space' home page will appear. Finally, you need to change your Confluence Server 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'. 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' buttons. In the 'Server Base Url' field of the 'Site Configuration' section, enter the full website address at which Confluence is running, as it should not be 'localhost'. For example, if your computer name is 'coopers' then the server base URL should be: `http://coopers:8090`. Alternatively, specify a website address such as `http://www.foobar.com:8090`. Scroll down to the end of the page and click the 'Save' button. Log out of Confluence, but leave the Confluence server running. (Move your cursor over the name 'Charlie of Atlassian' and click 'Log Out'.) Screenshot 2 (click to enlarge): Home page of the Confluence demo space Problems? Please go immediately to the Dragon Slayers' Forum. Victory? Please continue. ## Step 4. Hook Confluence up to Crowd Follow the steps below to hook Confluence up to Crowd for SSO and centralised user management. If Crowd is not already running, start it up by running {`CROWD_INSTALL}/start_crowd.bat` and go to your Crowd URL in your browser, e.g. `http://www.foobar.com:8095/crowd`. Log in to Crowd with username `charlie`. Click 'Applications' in the top navigation bar. The 'Application Browser' will appear. Click 'Add Application' in the left-hand menu. This will display the first screen for the 'Add Application' wizard for Crowd. Enter the following information: Application Type: `Confluence` Name: `confluence` Description: `Atlassian Confluence` Password – Enter a password that Confluence will use to access Crowd and enter it again to confirm it. URL – Enter the base URL of your Confluence site, as configured in step 3 above, e.g. `http://www.foobar.com:8090`. 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 that you created in Dragons Stage 1. Select 'Allow all users to authenticate'. Click 'Add Application'. Check the IP addresses for your Confluence application: Click the 'Remote Addresses' tab. Add your Confluence host name, e.g. `http://www.foobar.com:8090`. If it's not already present, add: `127.0.0.1`. Leave Crowd up and running, but shut down Confluence. (Press Ctrl+C in your Confluence server command window or run {`CONFLUENCE_INSTALL}\bin\shutdown.bat` (on Windows) or {`CONFLUENCE_INSTALL}/bin/shutdown.sh` (on UNIX).) Copy the Crowd client libraries and configuration files to your Confluence installation folder: Copy {`CROWD_INSTALL}/client/crowd-integration-client-2.0.3.jar` to {`CONFLUENCE_INSTALL}/confluence/WEB-INF/lib` Copy {`CROWD_INSTALL}/client/conf/crowd.properties` to {`CONFLUENCE_INSTALL}/confluence/WEB-INF/classes` Copy {`CROWD_INSTALL}/client/conf/crowd-ehcache.xml` to {`CONFLUENCE_INSTALL}/confluence/WEB-INF/classes` Edit the {`CONFLUENCE_INSTALL}/confluence/WEB-INF/classes/crowd.properties` file and change the following properties: application.name: `confluence` application.password – Enter the password that Confluence will use to access Crowd. This must be the same password as you entered in the Crowd 'Add Application' wizard above. Edit the {`CONFLUENCE_INSTALL}/confluence/WEB-INF/classes/atlassian-user.xml` file. Uncomment the Crowd provider and comment out all other lines of code. The code below should be the only lines of uncommented code in your file, after you have finished making these changes:
        <atlassian-user>
          <repositories>
            <crowd key="crowd" name="Crowd Repository"/>
          </repositories>
        </atlassian-user>
11. Edit the {`CONFLUENCE_INSTALL}/confluence/WEB-INF/classes/seraph-config.xml` file. Comment out the 'authenticator' element: `<authenticator class="com.atlassian.confluence.user.ConfluenceAuthenticator"/>` and replace it with: `<authenticator class="com.atlassian.crowd.integration.seraph.ConfluenceAuthenticator"/>` Your modifications should look similar to this:
        <security-config>
          ...
          <!-- <authenticator class="com.atlassian.confluence.user.ConfluenceAuthenticator"/> -->
          <authenticator class="com.atlassian.crowd.integration.seraph.ConfluenceAuthenticator"/>
          ...
        </security-config>
22. Start your Confluence server again, and go to your Confluence URL in your browser, e.g. `http://www.foobar.com:8090`. Log in to Confluence with username `charlie` and Charlie's password in Crowd. You are now authenticating via Crowd! Full details are in the Crowd documentation. Problems? Please go immediately to the Dragon Slayers' Forum. Victory? Please continue. ## Step 5. Get JIRA and Confluence Talking In this step you will set up the trusted communication channels between your JIRA and Confluence sites, so that you can display JIRA information on Confluence pages and Confluence information on the JIRA dashboard. You will also make a Confluence gadget available in JIRA, and make a JIRA gadget available in Confluence. First you will tell your Confluence server about your JIRA server. Open the 'Browse' menu at the top of the Confluence screen and select 'Confluence Admin'. The 'Administration Console' screen will appear. Click 'Trusted Applications' under 'Administration' in the left-hand panel. The 'View Trusted Applications' screen will appear, with a section called 'Request New Trusted Application Details'. Copy the base URL for your JIRA site (e.g. `http://coopers:8080` or `http://www.foobar.com:8080`) and paste it into the 'Base URL' field. Click 'Send Request'. The 'Edit New Trusted Application' screen will appear. Enter the following information: Name: `JIRA` – The default will be the URL you entered on the previous screen. You can safely change it to a more meaningful name. Leave the other fields at their default values. Click 'Save'. Now you will tell your JIRA server about your Confluence server. Keep Confluence open in your browser, and open another browser window/tab. Go to your JIRA site in the second window/tab. Because you are using Crowd for single sign-on, you should be automatically logged in to JIRA with username `charlie`. Click 'Administration' in JIRA's top navigation bar. The JIRA Administration console will appear. Click 'Trusted Applications' in the left-hand panel (in the 'System' section). The 'View Trusted Applications' screen will appear, with a section called 'Request New Trusted Application Details'. Copy the base URL for your Confluence site (e.g. `http://coopers:8090` or `http://www.foobar.com:8090`) and paste it into the 'Base URL' field. Click 'Send Request'. The 'Add New Trusted Application' screen will appear. Enter the following information: Application Name: `Confluence` – The default will be the URL you entered on the previous screen. You can safely change it to a more meaningful name. IP Address Matches – Add the following value to a new line in the box, leaving the existing values in place too: `127.0.0.1` Leave the other fields at their default values. Click 'Add'. Now you will make the Confluence 'Activity Stream' gadget available in JIRA, so that JIRA users will be able to add the gadget to their dashboards. Go to your Confluence browser window, open the 'Browse' menu and click 'Confluence Gadgets'. The 'Confluence Gadgets' popup window will appear, with a list of the gadgets that Confluence makes available. Find the 'Activity Stream' gadget and copy the URL from the 'Gadget URL' link into your clipboard. Close the 'Confluence Gadgets' popup window. 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 'Add Gadget to Directory'. The 'Add Gadget to Directory' popup window will appear. Paste the Confluence 'Activity Stream' gadget URL into the text box. The URL will look something like this:
        http://coopers:8090/rest/gadgets/1.0/g/com.atlassian.streams.confluence:activitystream-gadget/gadgets/conf-activitystream-gadget.xml
28. Click 'Add Gadget'. The Confluence gadget is now available in your JIRA gadget directory. You have not yet added it to your JIRA dashboard. We will do that in a later step. Now you will make the JIRA 'Pie Chart' gadget available in Confluence, so that Confluence users will be able to add the gadget to their wiki pages. Still on the JIRA 'Gadget Directory' screen, enter 'pie' into the search box at top right. The list of gadgets will change, to show only the gadgets that match your search term. Find the 'Pie Chart' gadget and and copy the URL from the 'Gadget URL' link into your clipboard. Go to your Confluence browser window, open the 'Browse' menu and click 'Confluence Admin'. The Confluence 'Administration Console' will appear. Click 'External Gadgets' under 'Configuration' in the left-hand panel. The 'External Gadgets' screen will appear. Paste the JIRA 'Pie Chart' gadget URL into the 'Gadget Specification URL' text box. The URL will look something like this:
        http://coopers:8080/rest/gadgets/1.0/g/com.atlassian.jira.gadgets:pie-chart-gadget/gadgets/piechart-gadget.xml
5. - Click 'Add'. Screenshot 3 (click to enlarge): Adding Confluence as a trusted application in JIRA Screenshot 4 (click to enlarge): The 'External Gadgets' setup screen in Confluence, with the 'Pie Chart' gadget The JIRA documentation has the details about trusted applications. Problems? Please go immediately to the Dragon Slayers' Forum. 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 a wiki site. It’s 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 'Create a 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, 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_badge04.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 the following text in the editor pane: This is the home of the Dragons space. To help you on your way, we've inserted some of our favourite macros on this home page. As you start creating pages, adding news items and commenting you'll see the macros below fill up with all the activity in your space. Press the 'Enter' key twice to make some space. Make sure your cursor is at the top of the editor pane. Click the 'Insert/Edit 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 go immediately to the Dragon Slayers' Forum. Victory? Please continue. ## Step 7. Add a JIRA Gadget and Macro to your Confluence Page Now you can put some interesting JIRA content into the space home page. Edit the Confluence page again. Place your cursor immediately after your Charlie badge image and press 'Enter' a few times to make some blank lines. Copy the following text and paste it into your wiki page: ### JIRA pie chart xxx ### JIRA issues xxx Now you will add a JIRA gadget to your Confluence page, displaying a pie chart of the issues in your JIRA Dragons project. Select the 'xxx' on the line below the heading 'JIRA pie chart'. Click the 'Insert/Edit Macro' icon in the editor toolbar. The 'Select Macro' popup window will appear. Enter 'pie' into the search textbox at top right. The list of macros and gadgets will change, to show only those that match your search term. Click the 'Pie Chart' macro. (This is actually the gadget.) The 'Insert "Pie Chart" Macro' screen will appear. Enter 'dra' into the 'Project or Saved Filter' text box. A selection list will drop down. Click 'Dragons (DRA)' under 'Projects'. Change 'Statistic Type' to 'Resolution'. Change 'Refresh Interval' to 'Every 15 Minutes'. Click 'Save'. The preview pane will show the pie chart of JIRA issues from your JIRA Dragons project. You should see a total of three issues, one fixed and two unresolved. Click 'Insert'. Click 'Save' to save your updated wiki page. Now you will add a JIRA Issues macro to your page, to display a dynamic list of issues drawn from your 'Dragons' project on your JIRA site. The first step is to define a filter in JIRA: Go to your JIRA browser window. Click the down arrow next to 'Issues' in the top navigation bar, then select 'Search for Issues'. The 'Issue Navigator' will appear. Select 'Dragons' in the 'Project' list on the left. Click 'View'. A list of issues will appear in the 'Issue Navigator'. You should see your three issues, `DRA-1`, `DRA-2` and `DRA-3`. Click 'Save it as a filter' in the left-hand panel. The 'Save Current Filter' screen will appear. Enter the following information: Name: `Dragons` Description: `Dragons` Click the 'Save' button at the bottom of the screen (not the one next to 'Add Shares'). The saved filter will appear, showing the same two issues. Click 'Views' at top right of the screen, right-click 'XML' and copy the link location for the 'XML' view into your clipboard. Add the JIRA Issues macro to your Confluence page: Go back to your Confluence browser window/tab. Edit your 'Dragons' home page again. Select the 'xxx' on the line below the heading 'JIRA issues' and replace it by pasting the content of your clipboard, for safe keeping. You will delete it again soon. It should be a JIRA filter URL that looks something like this:
         http://coopers:8080/sr/jira.issueviews:searchrequest-xml/10000/SearchRequest-10000.xml?tempMax=1000
   - Copy the following text into the next line on the Confluence page:
         {jiraissues:url=CONTENT}
Replace '`CONTENT`' with the JIRA filter URL from the line above, then delete the line containing the filter URL. Save the page. Screenshot 5 (click to enlarge): Your updated Dragons home page in Confluence Problems? Please go immediately to the Dragon Slayers' Forum. 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, move your cursor over 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'. Click 'Save'. Re-arrange your dashboard by dragging the 'Projects' gadget to the right and dropping it under the 'Assigned to Me' gadget. Drag the 'Agile' gadget to the bottom right too. 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 go immediately to the Dragon Slayers' Forum. 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 go immediately to the Dragon Slayers' Forum. Victory? Please continue.
| ##### Grab your Shield and Move to the Next Stage Tweet? Tweet. Go to Dragons Stage 5 - Install FishEye.
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)

Document generated by Confluence on Apr 07, 2010 22:35