This page last changed on Feb 11, 2010 by alui.


Beware, all ye who enter, for here there be dragons. You are embarking on stage 1 of the Atlassian Dragon Quest.

In this stage, you will install Java and a database (PostgreSQL) to hold the data for your Atlassian applications. Then you will set up Atlassian Crowd for centralised user management and single sign-on (SSO).

This procedure assumes that you already have JIRA installed. If you do not yet have JIRA, please ignore this page and start at Here Be Dragons instead.

Time estimate: This stage will take approximately 60 minutes.

On this page:

Step 1. Check your Java Development Kit

Requirements: Sun JDK 1.6 or higher. Note that the JRE alone is not enough.

If you do not have the right version of the Java Development Kit (JDK) already installed, follow the steps below to get it.

  1. Download the Sun Java SE Development Kit – Get the JDK 6u17. Do not get JDK 6u18 or later, as it contain a serious bug that affects Confluence performance.
  2. Follow the Sun installation instructions.
  3. Make sure you have a JAVA_HOME environment variable pointing to the root directory of the JDK. Some JDK installers set this automatically.
    • Check by typing one of the following into a command window, depending on your operating system.
      • On Windows: echo %JAVA_HOME%
      • On Linux or UNIX: echo $JAVA_HOME
    • If the above command does not show you the path to your JDK, please refer to the Crowd instructions on setting JAVA_HOME.

Step 2: Install your PostgreSQL Database Server

Below are the instructions for installing and setting up a PostgreSQL database server. If your JIRA installation is already using a different supported database server and you have a good technical knowledge of that server, you can choose to stick with it. However, for the purposes of this integrated setup exercise we do recommend PostgreSQL. Note that you will need the database server to hold the data for the other Atlassian applications that you will set up in later stages of this integration exercise.

Requirements: PostgreSQL version 8.4.x.

  1. Download PostgreSQL – Get the latest 8.4.x. For the simplest installation, choose one of the one-click installers.
  2. Install PostgreSQL. If you chose one of the PostgreSQL one-click installers, this is simple: Run the executable that you downloaded and follow the prompts. Ensure that you choose UTF8 (unicode) encoding when selecting the locale. If necessary, you can refer to the PostgreSQL installation instructions.
  3. Enter a password for the super user ('postgres').
  4. Accept the default port 5432.
  5. Accept all the other default settings.
  6. Download the PostgreSQL 8.4.x JDBC driver from http://jdbc.postgresql.org/download.html and save it locally for later use. Get the JDBC4 Postgresql Driver, Version 8.4-702.
    Internet Explorer may rename the file extension from '.jar' to '.zip' when you download it. If you are using Internet Explorer, please rename the file so that it has a '.jar' extension after downloading it.

Step 3. Create your Crowd Database in PostgreSQL

Now you will create a database where the Atlassian Crowd application will store its data, and the user that Crowd will use to connect to the database.

We're using pgAdmin III, the administration user interface supplied with PostgreSQL. If you used the one-click installer, pgAdmin III will be already installed on your computer.

  1. Start pgAdmin III.
  2. Add a new login role called 'crowduser':
    • Right-click 'Login Roles' and select 'New Login Role'.
    • Enter the role 'Role name': crowduser.
    • 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.
  3. Add a new database called 'crowd':
    • Right-click 'Databases' and select 'New Database'.
    • Enter the database 'Name': crowd.
    • Select the 'Owner': crowduser.
    • 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 Crowd user:
/opt/PostgreSQL/8.4/bin/createuser -S -d -r -P -E crowduser
# Create the Crowd database:
/opt/PostgreSQL/8.4/bin/createdb -O crowduser crowd
exit

Screenshot 1 (click to enlarge): Crowd database and user in PostgreSQL

Step 4. Install Crowd

Requirements: Crowd 2.0.7.

For Windows: (click to expand)
  1. Go to the Atlassian download centre.
  2. Download the 'Standalone (ZIP Archive)' file for Crowd 2.0.7.
  3. Unpack the zip archive into a directory of your choice, avoiding spaces in the directory name.
  4. Tell Crowd where to find its Crowd Home directory:
    • Edit the properties file at {CROWD_INSTALL}\crowd-webapp\WEB-INF\classes\crowd-init.properties.
    • Complete the following line and remove the # at the beginning of the line:
      crowd.home=
      For example:
      crowd.home=c:/data/crowd-home
      (Note the forward slashes.)
  5. Add the PostgreSQL JDBC driver JAR to your {CROWD_INSTALL}\apache-tomcat\lib directory.
  6. Start your Crowd server by running start_crowd.bat in the directory where you unpacked Crowd.
For UNIX or Linux: (click to expand)
  1. Go to the Atlassian download centre.
  2. Click the 'Linux' tab and download the 'Standalone (TAR.GZ Archive)' file for Crowd 2.0.7.
  3. Unpack the archive into a directory of your choice, avoiding spaces in the directory name.
  4. Tell Crowd where to find its Crowd Home directory:
    • Edit the properties file at {CROWD_INSTALL}/crowd-webapp/WEB-INF/classes/crowd-init.properties.
    • Complete the following line and remove the # at the beginning of the line:
      crowd.home=
      For example:
      crowd.home=/var/crowd-home
  5. Create the above Crowd Home directory if it does not already exist, because in some cases Crowd may not create it for you.
  6. Add the PostgreSQL JDBC driver JAR to your {CROWD_INSTALL}/apache-tomcat/lib directory.
  7. Start your Crowd server by executing start_crowd.sh in the directory where you unpacked Crowd.

Full details are in the Crowd installation guide.

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Step 5. Set Up Crowd

Now you can run Crowd's Setup Wizard, then add Charlie of Atlassian and the groups needed for JIRA, Confluence and the other applications.

  1. To access Crowd, go to your web browser and type this address: http://localhost:8095/crowd.
  2. The Crowd Setup Wizard will start up, to guide you through the process of setting up your Crowd server and creating an administration user. Detailed instructions are in the Crowd documentation. Here are the things you need to know for our Dragon Quest:
    • License – If you do not already have a Crowd license, follow the prompts on the Setup Wizard screen to get an evaluation license key.
    • Installation type – Select 'New Installation'.
    • Database configuration – Select 'JDBC Connection' then enter the following information to connect to your Crowd database (created above):
      • Database: PostgreSQL.
      • Driver Class Name – Leave this at the default value, i.e. org.postgresql.Driver.
      • JDBC URL – Leave this at the default value, i.e. jdbc:postgresql://localhost:5432/crowd.
      • Username: crowduser.
      • Password – The password you specified when creating your Crowd database above.
      • Hibernate Dialect – Leave this at the default value, i.e. org.hibernate.dialect.PostgreSQLDialect.
    • Deployment title – Enter a short, descriptive name. If you will only have one Crowd installation, then 'Crowd' is good enough.
    • Session Timeout – Leave this at the default value, i.e. 30
    • Base URL – Enter the full website address at which Crowd is running, not just 'localhost'. For example, if your computer name is 'coopers' then the base URL should be: http://coopers:8095/crowd. Or specify a website address, such as http://www.foobar.com:8095/crowd
    • Email details – Enter the details of your administrator email account. We recommend that you give your own email account details here.
    • Internal directory – This is the Crowd directory that will hold your users and groups. Enter the following information, and leave the other fields at the default values:
      • Name: Crowd.
      • Description: Crowd User Directory.
    • Default administrator – This is the Crowd super user. Enter the following information:
      • Email address – Enter the address of your administrator email account. We recommend that you give your own email address here.
      • Username – Enter the administrator's login name: charlie.
      • Password – Enter a password for the administrator account and enter it again to confirm it.
      • Enter a first name for your administrator: Charlie.
      • Enter a last name for your administrator: of Atlassian.
    • Integrated applications – Leave both selected, as is the default.
  3. Log in to Crowd with username charlie.
  4. Add the group that will hold all your JIRA users:
    • Click 'Groups' in the top navigation bar and then click 'Add Group'.
    • Enter the following information:
      • Group name: jira-users
      • Description: JIRA users
      • Directory: Crowd
      • Active – Leave this checkbox selected.
    • Click 'Create' to add the group.
  5. Add the following groups too, all in the same 'Crowd' directory. These groups are needed for JIRA, Confluence and Bamboo:
    • jira-developersJIRA developers
    • jira-administratorsJIRA administrators
    • confluence-usersConfluence users
    • confluence-administratorsConfluence administrators
    • bamboo-adminBamboo administrators
  6. Make Charlie of Atlassian an administrator in JIRA, Confluence and Bamboo by adding him to the relevant groups:
    • Click 'Users' in the the top navigation bar and find 'Charlie of Atlassian'.
    • Click the name to view Charlie's user information.
    • Click the 'Groups' tab under 'View User', then click 'Add Groups'.
    • The 'Add Groups' screen will appear. Click 'Search' to see all the groups in the directory.
    • Select the checkbox at top left, next to the 'Name' column, to select all groups.
    • Click 'Add Selected Groups' to add Charlie to the groups.

Screenshot 2 (click to enlarge): Adding Charlie to groups in Crowd

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Victory!

Charlie of Atlassian can now log into Crowd. If he checks his profile (using the 'My Profile' link at top right of the Crowd screen), he will see the groups he belongs to.

Screenshot 3 (click to enlarge): Charlie's profile showing the groups he belongs to

Problems? Please raise a support ticket for the product you're stuck on, or try the Dragon Slayers' Forum.
Victory? Please continue.

Take a Bow and Move to the Next Stage
Document generated by Confluence on Feb 27, 2011 17:37