Install Cognos 8.4.1 on Ubuntu 10.04

These are instructions for installing IBM Cognos 8.4.1 on Ubuntu 10.04.  I found the installation process on Ubuntu 10.04 to be quite painful due to lack of specific documentation (Ubuntu is not a supported IBM Cognos 8.x platform).  So, I documented the process I used here... mainly in case I have to repeat it on another machine... :-)

Configuration:
Ubuntu 10.04 Desktop Edition (not server)
4 Gb RAM
Intel Core Duo 1.83 GHz
Install consumed about 1Gb of disk space

Pre-requisites:
Apache2
Cognos 8.4.1 installation files already downloaded

These instructions assume you have downloaded the Cognos 8.4.1 installation files.  If using the Cognos installation CDs, look for the issetup file within the appropriate Operating System directory and run using the instructions below.  More info here.

STEP 1 - Run Cognos 8 BI Server Install

Run all of the following commands EXCEPT the last one...

user@host:$ cd ~/Downloads/DownloadDirector
user@host:$ mkdir cognos_8.4.1_bi_server
user@host:$ cd cognos_8.4.1_bi_server
user@host:$ tar -xzvf ../cognos_8.4.1_bi_server.tar.gz
user@host:$ sudo ./issetup

I initially encountered the following error:

Error while loading shared libraries: libXm.so.3: cannot open shared object file: No such file or directory.

This is because the Cognos 8.4.1 installer requires the libXm.so.3 library, which is an older version than Ubuntu 10.04 installs.  To resolve, simply install it from the repository.  I also read a few articles about creating symbolic links to later versions of libXm.so, but this was easy and I figured would create the least amount of issues with the Cognos installers.

user@host:$ sudo apt-get install libmotif3

Now, execute:

user@host:$ sudo ./issetup

Make sure you run issetup using the sudo command or you will get permissions errors if you're installing somewhere other than your home directory.

During the install process select Cognos BI server components, then select install Cognos Content Store unless you have one of the supported databases already set up.  I installed everything to:

/opt/cognos/c8

STEP 2 - Install Cognos 8 BI Samples (optional)

Run the following commands:

user@host:$ cd ~/Downloads/DownloadDirector
user@host:$ mkdir cognos_8_bi_samples
user@host:$ cd cognos_8_bi_samples
user@host:$ tar -xzvf ../cognos_8_bi_samples.tar.gz
user@host:$ sudo ./issetup

Accept the defaults, acknowledge the warning to install the Cognos 8 BI Samples into the same directory where you installed the Cognos BI server components, in my case this was:

/opt/cognos/c8

If you want to use the Cognos sample data, after completing the Cognos installation steps you'll need to:

1. Restore the sample databases
2. Set up data source connections within Cognos for the sample databases
3. Import the sample content (reports, queries, etc.)

NOTE ON SAMPLE DATA: Although you can import the sample content into the Apache Derby database that comes with Cognos 8.4.1, the sample database backup files are only provided in Oracle and DB2 format. If you are not running either Oracle or DB2, you can choose to only import the sample content into the Derby database (assuming you selected the option to install the Cognos Content Store during the install). This will allow you to view reports, queries, etc. within Report Studio, Query Studio, Analysis Studio, etc. however you will not actually be able to run any of the reports against a database and view the results.

If you want to use the Cognos 8 sample data, see my instructions on setting up the Cognos 8 sample data in DB2.

STEP 3 - Set Java environment, configure Cognos 8, and start Cognos services

First copy the Cognos java encryption file to your JAVA_HOME/jre/lib/ext directory.

In my case, JAVA_HOME=/usr/lib/jvm/java-6-sun

user@host:$ sudo cp /opt/cognos/c8/bin/jre/1.5.0/lib/ext/bcprov-jdk14-134.jar /usr/lib/jvm/java-6-sun/jre/lib/ext/bcprov-jdk14-134.jar

Don't worry about the fact that Cognos 8 shipped with java 5, it will run with java 6.

Next is where I ran into a couple of tough issues... I did a ton of things to try and get the Cognos Configuration Manager to run.  You start the Cognos Configuration Manager with the following command:

user@host:$ cd /opt/cognos/c8/bin
user@host:$ ./cogconfig.sh

However, I could not get it to run.  First I ran into a permissions issue, then a JAVA_HOME environment variable issue, and an X-windows display issue.  Here's what I finally did to resolve:

user@host:$ sudo chown -R user:cognos /opt/cognos
user@host:$ JAVA_HOME=/usr/lib/jvm/java-6-sun/jre ./cogconfig.sh

Where user = your user name

I had created a cognos user and group on my Ubuntu system and had been trying to run the Cognos Configuration Manager under that user id, however no matter what I tried (editing ~/.profile or /etc/bash.bashrc) the utility came back with a JAVA_HOME undefined error and exited.  Even when I passed the correct java path in the command statement.  However, I found that if I changed ownership of the entire /opt/cognos directory structure to my user name, and also passed the correct java path in the command statement... voila, almost...

Then, I got another error about being unable to find libstdc++5... this is because Ubuntu 10.04 has a newer version, and libstdc++5 is no longer in the software repository, so

user@host:$ sudo apt-get install libstdc++5

will not work.

error: 27/04/2011,13:49:21,Err,java.lang.UnsatisfiedLinkError: /opt/cognos/c8/bin/libJCAM_Crypto_JNI.so: libstdc++.so.5: cannot open shared object file: No such file or directory, com.cognos.crconfig.CRConfigFrame.initDataManager(CRConfigFrame.java:549)

To resolve the above error, go here, and download the libstdc++5 package, and install.  Then re-run:

user@host:$ JAVA_HOME=/usr/lib/jvm/java-6-sun/jre ./cogconfig.sh

The Cognos Configuration Manager should now run without issue.  Follow the IBM guide for configuration of Cognos 8 located here.  The link is to the page called Start the IBM Cognos 8 Services under Installing and Configuring IBM Cognos 8 Components on One Computer.  If you're setting up a test environment on a single server with the Cognos Content Store as your database, then you can skip the security, mail server account, and data source connections.  The tests all completed successfully, and I was able to start the Cognos services without issue.

STEP 4 - Configure Apache

A correct, or perhaps I should say a "functional," Apache configuration for Cognos 8.4.1 on Ubuntu 10.04 eluded me for quite some time.  First, I set up virtual sites and the appropriate config files, but still could not get Cognos to work.  I dealt with permissions issues causing 403 errors, 404 errors, and cgi binaries downloading within the browser instead of being executed by the server.  The last issue with cgi binaries was the issue that held me up for quite some time.

Give Apache Access to c8 Directory & Change Permissions

user@host:$ sudo chmod -R 0775 /opt/cognos/c8
user@host:$ sudo chown -R user:www-data /opt/cognos/c8

Assigning ownership to the www-data group ensures that the Apache web server has access.

Set up Virtual Site for Cognos8

First create a cognos8 file in /etc/apache2/sites-available from a copy of the default file.  Then execute the a2ensite command to tell Apache to enable the new virtual site.

user@host:$ sudo cp /etc/apache2/sites-available/default /etc/apache2/sites-available/cognos8
user@host:$ sudo a2ensite cognos8

Edit the Cognos8 Virtual Site Configuration

Edit the cognos8 file located in /etc/apache2/site-available. Change your entry as appropriate based on your directory locations.

<VirtualHost *:80>
 ServerAdmin webmaster@localhost 

 DocumentRoot /var/www/cognos8

 <Directory />
  Options FollowSymLinks
  AllowOverride All
 </Directory>

 ScriptAlias cognos8/cgi-bin/ /var/www/cognos8/cgi-bin/
 <Directory "/var/www/cognos8/cgi-bin">
  AllowOverride FileInfo
  Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
  SetHandler cgi-script
  Order Allow,Deny
  Allow from All
 </Directory>

 Alias cognos8 /var/www/cognos8
 <Directory /var/www/cognos8/>
  Options FollowSymLinks
  AllowOverride FileInfo
  Order Allow,Deny
  Allow from All
 </Directory>

Edit the Default Virtual Site Configuration

Edit the default file located in /etc/apache2/site-available. Change your entry as appropriate based on your directory locations. SPECIAL NOTE: the key change in this file was adding the ScriptAlias for cognos8/cgi-bin. Until I did that, Apache just downloaded the cgi binaries to my web browser instead of executing them.

<VirtualHost *:80>
 ServerAdmin webmaster@localhost

 DocumentRoot /var/www
 <Directory />
  Options FollowSymLinks
  AllowOverride All
 </Directory>
 <Directory /var/www/>
  Options Indexes FollowSymLinks MultiViews
  AllowOverride All
  Order allow,deny
  allow from all
 </Directory>

 ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
 <Directory "/usr/lib/cgi-bin">
  AllowOverride None
  Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
  Order allow,deny
  Allow from all
 </Directory>

 ScriptAlias cognos8/cgi-bin/ /var/www/cognos8/cgi-bin/
 <Directory "/var/www/cognos8/cgi-bin">
  AllowOverride FileInfo
  Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
  SetHandler cgi-script
  Order Allow,Deny
  Allow from All
 </Directory>

Restart Apache

user@host:$ sudo /etc/init.d/apache2 restart

Test Cognos

Go to http://localhost/cognos8 in your browser, if you've done everything correctly, you should see the Welcome to IBM Cognos 8 screen in Cognos Connections: