Confluence and Crowd Installation notes.

Another round of Atlassian applications installations, this time only Jira and Confluence with a Crowd backend for single sign on. We’ll start with Crowd and Confluence, check out the series to find the Jira notes.

Here are the notes I made as I went through this round of installation. It should be much simpler than my previous installation where there were numerous other applications installed. For this we need Crowd, Jira, and Confluence, along with supporting apps: Tomcat, Java, MySQL and maybe Apache.

Get a Linux box. I’m using a virtual JeOS Centos 5.2 installation inside an Oracle VM manager.
Get yum working. We have a local repo for base apps, and added Dag’s repo to get some extra packages.
Do a yum -y update all, you should always have the latest unless otherwise required. At least the lastest available from your package manager so things go smoothly. ((Sometimes it is necessary to use a specific newer or older version of a package. This tends to break package managers so be careful. I rather err for stability than the bleeding edge))
Install and configure Java.
Use the rpm.bin file from Sun to install Java ((If you’re doing this in a non RPM based system, use the regular bin file))
After a few screens of licensing agreement, it will install Java and all the necessary rpms. Notice that

# which java

works because we used the rpm installation.
Set JAVA_HOME:
I know that the JAVA_HOME for an RPM system generally is /usr/java/default/bin, to find out, you can use a combination of which java, file `which java`, and tracking it down that way until you find it. The following steps show how to add this to all users under the /etc/profile. Before you add it there permanently, you could check it on the command line:

[root@xxxx_webapp_01 bin]# which java
/usr/bin/java
[root@xxxx_webapp_01 bin]# file `which java`
/usr/bin/java: symbolic link to `/usr/java/default/bin/java'
[root@xxxx_webapp_01 bin]# JAVA_HOME=/usr/java/default/bin/
[root@xxxx_webapp_01 bin]# $JAVA_HOME/java -version
java version "1.6.0_14"
Java(TM) SE Runtime Environment (build 1.6.0_14-b08)
Java HotSpot(TM) 64-Bit Server VM (build 14.0-b16, mixed mode)
[root@xxxx_webapp_01 bin]#


We got the version of java by calling JAVA_HOME/java -version so this means it should work if we just add a couple lines to the /etc/profile. Then after loging out and back in, you should be able to run the commands we tested earlier without having to manually set JAVA_HOME

[root@xxxx_webapp_01 ~]# tail /etc/profile
        . $i
    fi
done

# JAVA HOME
export JAVA_HOME=/usr/java/default/bin
export PATH=$JAVA_HOME/bin:$PATH
# JAVA HOME END

[root@xxxx_webapp_01 ~]# echo $JAVA_HOME
/usr/java/default/bin
[root@xxxx_webapp_01 ~]# java -version
java version "1.6.0_14"
Java(TM) SE Runtime Environment (build 1.6.0_14-b08)
Java HotSpot(TM) 64-Bit Server VM (build 14.0-b16, mixed mode)
[root@xxxx_webapp_01 ~]#

From past experience, I know that it is better to use Tomcat if you’re going to manage more than one Atlassian app, instead of using the standalone packages that Atlassian provides. Now we gotta install Tomcat, we’re going with the latest 6.x version apache-tomcat-6.0.20.tar.gz. Get the package, untar it and then refer to the installation docs to get Tomcat installed and running ((I might have some notes about Tomcat and running it and stuff, but the installation and configuration for it is beyond the scope of this post. Installing, configuring and troubleshooting tomcat is a topic for another day)) http://tomcat.apache.org/tomcat-6.0-doc/setup.html.

Crap, it won’t run! Oh yeah… I remember now, we need JRE for this not JDK… so we’ll get that, http://java.sun.com/javase/downloads/index.jsp Now I remember what a PITA this thing is…

… I had to work on a couple of things, so the following notes may feel like they’re separate… A couple days later…

I got java installed, and now Tomcat is running. ((Sorry kids, no notes for you on this one. Right now my notes on this are a scramble of post-its, google notebook, history and shell commands. I had to move fast because of the urgency on finishing this for a client. Wouldn’t it be nice to have a script that just does all this for me? I initially had a system ready to go with all the stuff installed, the idea would be to just clone the system and customize it for the next time. Unfortunately I haven’t had time to keep it up to date and at least 2 or 3 versions for the major software packages have been released so I couldn’t honestly give them such an old installation.))

Tomcat 6 Installed and running successfully

Tomcat 6 Installed and running successfully

Get the applications you need ((This shows the standalone tars for the Atlassian apps, in fact I used the jar versions, you’ll have to dig a little bit around for them, when I get some time I’ll fix this to make it more clear))

wget http://www.atlassian.com/software/crowd/downloads/binary/atlassian-crowd-1.6.1.tar.gz
wget http://www.atlassian.com/software/confluence/downloads/binary/confluence-3.0.0_01-std.tar.gz
wget http://www.atlassian.com/software/jira/downloads/binary/atlassian-jira-standard-3.13.4-standalone.tar.gz

No onto the Actual application installations. First up is MySQL server, these are just my history commands with a quick comment to explain.

yum -y install mysql mysql-server #Installs server from repository, not latest and greatest but stable and quick.
mysql -uroot     #Get on the mysql console to make sure it works
service mysqld start # I guess you gotta start it first huh?
chkconfig --level 3 mysqld on # Make sure it'll start after a reboot
mysql -uroot # Now get on and check things out.
vim /etc/my.cnf # Configure your options for mysqld.
service mysqld restart # Just for kicks.

I really like the command line but when it comes to managing MySQL, the MySQL Administrator kicks ass IMO. So I give myself local network permissions to remotely connect to the box with the Administrator and then I do the rest from the GUI ((Generally speaking, I prefer the command line, but lately some of the GUIs for several systems we use have proven to be as good and sometimes even better (yikes!) than the CLI. This one is debatable, if you’re a MySQL guru and you know all the statements then stick to the CLI, but if you’re fuzzy about commands and structure, or you like the visual representation then I highly recommend the MySQL Administrator as well as its companion the SQL Query Browser.))
To get network access to the system so you can use the MySQL Administrator, log into mysql with the root user, then do this:

GRANT ALL PRIVILEGES ON *.* TO 'username'@'your.ip.address' identified by "password_of_your_choice";

Follow the instructions to create the usernames and databases for each application. Instructions are available for each one. Here is Crowd, Confluence & Jira. Note that the docs for Crowd are incomplete since they don’t officially support TC 6, the commons/lib folder they call for, does not exist. You’ll need to review this official doc, and maybe this post can shed some light as well: http://www.nabble.com/Tomcat-6,-JNDI-datasource-no-longer-work-td14240562.html. In summary, the driver goes to $CATALINA_HOME/lib not $CATALINA_HOME/commons/lib. The MySQL driver I’m using is here:mysql java connector 5.0.8.

[root@xxxx_webapp_01 ~]# cp mysql-connector-java-5.0.8-bin.jar $CATALINA_HOME/lib/
[root@xxxx_webapp_01 ~]# ls !$
ls $CATALINA_HOME/lib/
annotations-api.jar  catalina-ha.jar  catalina-tribes.jar  jasper-el.jar  jasper-jdt.jar  mysql-connector-java-5.0.8-bin.jar  tomcat-coyote.jar  tomcat-i18n-es.jar  tomcat-i18n-ja.jar
catalina-ant.jar     catalina.jar     el-api.jar           jasper.jar     jsp-api.jar     servlet-api.jar                     tomcat-dbcp.jar    tomcat-i18n-fr.jar
[root@xxxx_webapp_01 ~]#

I like to create all usernames and databases at once since there isn’t much to it if you do them all at once. Each username should only have access to its own database, and only from localhost ((Unless of course you’re installing a multi-node system where you might require access from other hosts, I don’t)).

MySQL Administrator showing the permissions for the crowduser

MySQL Administrator showing the permissions for the crowduser

Next up is to add the shared jars, they go in the same place as the mysql driver; as stated in the Atlassian docs, you can get these files from the standalone package for Crowd, I simply copied them from another server where we already have this working, I put them at home then copy them out to their final spot.

[root@xxxx_webapp_01 ~]# ls -lt ~
total 233444
-rw-r--r-- 1 root root   388864 Jun 12 09:13 mail-1.4.jar
-rw-r--r-- 1 root root     8382 Jun 12 09:13 jta-1.0.1B.jar
-rw-r--r-- 1 root root     8809 Jun 12 09:13 jta-1.0.1.jar
-rw-r--r-- 1 root root   540852 Jun 12 08:48 mysql-connector-java-5.0.8-bin.jar

[root@xxxx_webapp_01 ~]# cp -u ~/*.jar $CATALINA_HOME/lib/

[root@xxxx_webapp_01 ~]# ls -lat $CATALINA_HOME/lib/
total 5864
-rw-r--r--  1 root root  388864 Jun 12  2009 mail-1.4.jar
drwxr-xr-x  2 root root    4096 Jun 12  2009 .
-rw-r--r--  1 root root    8809 Jun 12  2009 jta-1.0.1.jar
-rw-r--r--  1 root root    8382 Jun 12  2009 jta-1.0.1B.jar
-rw-r--r--  1 root root   62983 Jun 12  2009 activation-1.1.jar
-rw-r--r--  1 root root  540852 Jun 12 08:54 mysql-connector-java-5.0.8-bin.jar

Lets finish preparing the directories to host all three apps, I use symlinks to maintain easy to read and maintain scripts. For example “jira” will point to the actual jira folder. That way if you upgrade Jira for example, you don’t have to go and find all the scripts that have atlassian-jira-standard-3.13.4-standalone. You simply make the symlink jira point to the new folder, say atlassian-jira-standard-4.x.x.x-standalone. This is also great for testing.

[root@XXXX_webapp_01 atlassian]# pwd
/opt/atlassian

[root@XXXX_webapp_01 atlassian]# ls -la
total 20
drwxr-xr-x  5 root root 4096 Jun 12  2009 .
drwxr-xr-x  7 root root 4096 Jun 12 09:38 ..
drwxr-xr-x 10 root root 4096 Feb 16 23:18 atlassian-crowd-1.6.1
drwxr-xr-x 15 root root 4096 Jun 12  2009 atlassian-jira-standard-3.13.4-standalone
drwxr-xr-x 11 root root 4096 Jun 12  2009 confluence-3.0.0_01-std

[root@XXXX_webapp_01 atlassian]# ln -s atlassian-crowd-1.6.1 crowd
[root@XXXX_webapp_01 atlassian]# ln -s atlassian-jira-standard-3.13.4-standalone jira
[root@XXXX_webapp_01 atlassian]# ln -s confluence-3.0.0_01-std confluence
[root@XXXX_webapp_01 atlassian]# ls -la

drwxr-xr-x 10 root root 4096 Feb 16 23:18 atlassian-crowd-1.6.1
drwxr-xr-x 15 root root 4096 Jun 12  2009 atlassian-jira-standard-3.13.4-standalone
lrwxrwxrwx  1 root root   23 Jun 12  2009 confluence -> confluence-3.0.0_01-std
drwxr-xr-x 11 root root 4096 Jun 12  2009 confluence-3.0.0_01-std
lrwxrwxrwx  1 root root   21 Jun 12  2009 crowd -> atlassian-crowd-1.6.1
lrwxrwxrwx  1 root root   41 Jun 12  2009 jira -> atlassian-jira-standard-3.13.4-standalone

You’ll need to add a “crowd.xml” file to the Tomcat deploy directory, I’m using the exploded war for crowd. You also need to configure the crowd properties file and specify the home for crowd, I made it to be /opt/atlassian/crowd-home. As much as I hate Tomcat, this is *all* you have to do to deploy Crowd onto Tomcat. After this is done then you still have to go through the Crowd wizard configuration.

[10:43 AM] xxxx_webapp_01:/opt/apache-tomcat-6.0.20/lib # cd /opt/apache-tomcat-6.0.20/conf/Catalina/localhost/
[10:43 AM] xxxx_webapp_01:/opt/apache-tomcat-6.0.20/conf/Catalina/localhost # ls -la
total 20
drwxr-xr-x 2 root root 4096 Jun 12 10:29 ./
drwxr-xr-x 3 root root 4096 Jun  9 12:36 ../
-rw-r--r-- 1 root root   75 Jun 12 10:29 crowd.xml
-rw-r--r-- 1 root root  885 Jun  9 12:36 host-manager.xml
-rw-r--r-- 1 root root  885 Jun  9 12:36 manager.xml

this goes in it, just match your path


The wizard configuration is pretty straight forward, you’ll configure the license which you can obtain from atlassian directly at the time of your configuration; you’ll give them your server ID, and they’ll in turn give you a license key to match. After the license you’ll configure the database, using jdbc fill in the details

Fill in your details for the JDBC MySQL connection.

Fill in your details for the JDBC MySQL connection.

The next screen allows you to name the server, give it a timeout value and specify the base url for crowd. I left mine at default and just added the name of the server.

Customize your server and specify the URL. Defaults work well.

Customize your server and specify the URL. Defaults work well.

The next two screens deal with some more configuration options, like your mail relay and internal directory information along with some password parameters. Then you’ll configure the administrator account, this is important note it all down or save it somewhere so you can get in to the server once it is ready to go. After a couple more screens then you should be ready to go.

Success!

Success!

Use your administrator username and password to login and you can see what the Crowd administrator console has to offer. After we install each of the applications, we’ll have to come back here and configure them in Crowd to setup the Single Sign On procedures.

A view of the applications available on a new Crowd installation.

A view of the applications available on a new Crowd installation.

Put Crowd to rest for now and lets install Confluence on Tomcat.

The installation for Confluence is similar to Crowds. Explode the war, make a home for confluence, configure the confluence properties file, then add the context file (confluence to Tomcat.

XXXX_webapp_01:/opt/atlassian # mkdir /opt/atlassian/confluence-home

[12:09 PM] XXXX_webapp_01:/opt/atlassian/confluence/WEB-INF/classes # vim confluence-init.properties 
[12:09 PM] XXXX_webapp_01:/opt/atlassian/confluence/WEB-INF/classes # cat !$
cat confluence-init.properties
confluence.home=/opt/atlassian/confluence-home

[12:06 PM] XXXX_webapp_01: cd /opt/apache-tomcat-6.0.20/conf/Catalina/localhost
[12:06 PM] XXXX_webapp_01:/opt/apache-tomcat-6.0.20/conf/Catalina/localhost # vim confluence.xml 
[12:06 PM] XXXX_webapp_01:/opt/apache-tomcat-6.0.20/conf/Catalina/localhost # cat !$
cat confluence.xml

Then you should be able to restart Tomcat and have http://your-tomcatserver/confluence available. It may take a little while to start, it did for me and it freaked me out a little bit, especially when I got this error.

requested resource not available

requested resource not available

If you haven’t created the database for confluence, you should do it before starting the Confluence Setup Wizard. The wizard will walk you through the configuration, since we’re using an external database, we’ll need to do the Custom installation. Pick MySQL and then configure the username and password for the connection.

License and type of installation, we need custom.

License and type of installation, we need custom.

The database instructions for Confluence aren’t as clear as the one for Crowd. I think they assume that you’re migrating from a standalone installation to an external database installation. I mention this because I was concerned that the mysql connector also should be put into the confluence lib directory, not just in the $CATALINA_HOME/lib/ directory. So I just copied this file from the tomcat shared lib to the confluence lib. ((I did this even after I had started the Configuration Wizard and it just worked.))

[12:14 PM] XXXX_webapp_01:/opt/apache-tomcat-6.0.20/conf/Catalina/localhost # cp /opt/apache-tomcat-6.0.20/lib/mysql-connector-java-5.0.8-bin.jar /opt/atlassian/confluence/WEB-INF/lib/
[12:38 PM] XXXX_webapp_01:/opt/apache-tomcat-6.0.20/conf/Catalina/localhost # ls -lt !$
ls -lt /opt/atlassian/confluence/WEB-INF/lib/
total 54952
-rw-r--r-- 1 root root  540852 Jun 12  2009 mysql-connector-java-5.0.8-bin.jar

The next few steps are self explanatory and should lead you to a successful installation of confluence, I picked the option to have sample data in place since the users for this instance of Confluence might not have ever used a wiki; this should help them figure it out easily. Hopefully you get this:

Success at installing confluence, ready to go.

Success at installing confluence, ready to go.

Now that Confluence is installed, lets integrate confluence into Crowd. I’ll be following this document http://confluence.atlassian.com/display/CROWD/Integrating+Crowd+with+Atlassian+Confluence

I will be using a single directory instead of the way the document suggests to have a directory per application. This is easier to manage IMO. ((I went back and made this modification after I took some screenshots, so some of the pictures may not match exactly what I’m saying))

Created the administrator and users group

Created the administrator and users group

See that the admin belongs to both users and administrator groups.

See that the admin belongs to both users and administrator groups.

With the directory, groups and at least one user configured, we’re ready to add the Confluence application. Follow the steps to define the application as described in the documentation. Note the username and password fields aren’t known at this time so you can define them now, you’ll need to use these later in the properties file for crowd. Complete the steps to add the application. Grant the confluence-users and confluence-administrators to log into Confluence.

Shows that both administrators and users groups are part of the application.

Shows that both administrators and users groups are part of the application.


— Other notes
Some of the properties files for the applications have an opening and clossing “Context” tag. I used what seems like a short-notation style in which the closing tag is ommitted and you just put a “/>” to close the “ and .

I noticed that my instructions have a mistake, instead of using the crowd standalone, I actually used the crowd war file same for Confluence. You need to download the war versions of these instead of the standalone versions. Keep your eyes out for that info on the Atlassian docs for now until I get a chance to fix this.

Hey, I should tell you, this post contains affiliate links. That means that if you buy one of the services or products linked to, the company may pay me a small commission. This is Affiliate Marketing and it is how I monetize the blog, in fact it is how I make my living. Do you want to learn how to do this? Download my Book where I tell you all about it.