Atlassian Integration Guide : Dragons Stage 4 - Install Confluence This page last changed on Oct 05, 2009 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 create a wiki space and add a dynamic list of JIRA issues to a wiki page. You will also hook Confluence up to Crowd for SSO and centralised user management. Time estimate: This stage will take approximately 30 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. Configure JIRA to Trust Confluence Step 6. Create a Wiki Space 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.0.1. For Windows: (click to expand) Go to the Atlassian download centre. Download the 'Standalone (ZIP Archive)' file for Confluence 3.0.1. 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`. Copy the PostgreSQL JDBC driver JAR (downloaded in Dragons Stage 1) to your {`CONFLUENCE_INSTALL}\confluence\WEB-INF\lib` directory. 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.0.1. 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`. Copy the PostgreSQL JDBC driver JAR (downloaded in Dragons Stage 1) to your {`CONFLUENCE_INSTALL}/confluence/WEB-INF/lib` directory. 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.1.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 the default repository so that the contents of the file is:
        <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>
6. - 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. Configure JIRA to Trust Confluence In this step you will set up a trusted communication channel between your JIRA and Confluence sites, so that you can display JIRA information on a Confluence wiki page. 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 the top navigation bar. The JIRA Administration console will open. 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: `127.0.0.1` – Add this address to a new line in the box. Leave the other fields at their default values. Click 'Add'. Full details are in the JIRA documentation. 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 for use in the subsequent stages of the Atlassian Dragon Quest. 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 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, 'Default Theme'). 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. 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 select the Charlie badge image that you saved earlier. Click 'Attach' to upload the image. The image file name will appear in the 'Filename' textbox. Click 'OK'. The image will appear in the editor pane of your home page. 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: 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 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 two issues, `DRA-1` and `DRA-2`. 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. Place your cursor immediately after your Charlie badge image and press 'Enter' a few times to make some blank lines. Paste the content of your clipboard into a blank line, 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. ## Victory! You now have a 'Dragons' space in your Confluence wiki. Your space home page has a Charlie badge and a dynamically-updated list of JIRA issues. Screenshot 3 (click to enlarge): Home page of the Dragons space 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)

Document generated by Confluence on Oct 06, 2009 00:43