These instructions describe the setup of Collaboa on Ubuntu Edgy, but have also been tested working on Ubuntu Dapper (6.06 LTS). This page should probably be renamed to “InstallingOnUbuntu”?

I have tried to make these instructions as clear and complete as possible, but invariably there will be steps missing from this outline. I hope that this HOWTO provides enough information to guide the experienced user through the process of setting up the application on Ubuntu under an Apache / mod_fcgid environment.

Step 1. Install Rails from gem package

Firstly, if you have installed the version of rails that is packaged with Ubuntu, remove it using:

$ sudo apt-get remove rails

To install latest rails from gem repository, use the following:

$ gem install rails --include-dependencies

Step 2. Install dependencies

Collaboa has a number of dependencies that you will need to install before the application will work properly. They are xhtmldiff, diff-lcs and the Ruby bindings to Subversion. The first two are installed using the gem tool whilst the last one is installed from an Ubuntu package.

$ gem install xhtmldiff --include-dependencies

$ sudo apt-get install libsvn-ruby

Hint: If you do not install the Ruby bindings for Subversion, when you attempt to install Collaboa you will receive the error message “no such file to load – svn/core”.

Step 3. Install Collaboa

Now that you have installed the necessary dependencies, read the INSTALL file that ships with the Collaboa application. It outlines the main steps required to install the application and database. (Note: you will typically require mysql as your back-end database server).

The basic approach is to setup your database.yml file with sensible values for your collaboa install, to configure your Mysql instance in preparation for data load, and then to run the following:

$ RAILS_ENV="production" rake db:schema:load
$ RAILS_ENV="production" ruby db/default_content.rb

This step should populate your database with a schema and default settings for the application. If you receive an error at this point it typically means that your mysql database is not set up correctly!

Hint: Check database settings

Check the username and password credentials you entered into database.yml by running the mysql command line prompt:

$ mysql -u <collaboa_user> <collaboa_database>
Enter password: ****** (your collaboa password)

If you are unable to connect to the database it is probably an issue of grant permissions. See the Additional Hints section below for some tips on setting up your Mysql database properly.

4. Setup Apache2 with mod_fcgid

To run Collaboa under mod_fcgid you will need to install (at least) the following packages:

$ sudo apt-get install apache2 libapache2-mod-fcgid

This section assumes you are setting up Collaboa using an Apache2 Virtual Host. If you have selected another model for Apache deployment (e.g. an Alias directive within an existing website URL) you will probably need to write your own Apache2 configuration (though some settings may be similar to the ones below). (Note: For starters, if you choose Alias based hosting, you will probably need to set the RewriteBase directive in public/.htaccess to make your pages work. This step is not necessary for Virtual Host deployments).

<VirtualHost *>
  ServerName your.site.com
  ServerAdmin webmaster@your.site.com
  DocumentRoot /var/www/your_collaboa_instance/public/
  ErrorLog /var/log/apache2/your_collaboa_instance-error.log
  CustomLog /var/log/apache2/your_collaboa_instance-access.log combined

  DefaultInitEnv RAILS_ENV production

  <Directory /var/www/your_collaboa_instance/public/ >
    Options ExecCGI FollowSymLinks
    AllowOverride all
    Order allow,deny
    Allow from all
  </Directory>

</VirtualHost>

5. Tweak Collaboa application settings

Important: In public/.htaccess, two changes need to be made:

• Comment out ALL references to AddHandler directives (very important!)
• Change dispatch.cgi to dispatch.fcgi (very important!)

The key changes you need to make appear below:

# General Apache options
#AddHandler fastcgi-script .fcgi
#AddHandler cgi-script .cgi
#AddHandler fcgid-script .fcgi
Options +FollowSymLinks +ExecCGI

...

RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]

...

Note: You may be wondering where Apache2 obtains its mod_fcgid configuration and AddHandler information? These settings are contained in the file /etc/apache2/mods-available/fcgid.conf, which is automatically installed when you install the fcgid module.

6. Test your configuration

Restart your Apache2 instance:

$ sudo /etc/init.d/apache2 restart

Now, hit your website using the URL you have defined in the Virtual Host directive. Once your request has been served, check your system to verify that you are running an instance of the fcgi process.

$ ps aux | grep dispatch
www-data  2271 63.0  2.2  31004 23776 ?        S    22:09   0:03 ruby /var/www/your_collaboa/public/dispatch.fcgi
someuser  2274  0.0  0.0   2876   792 pts/1    R+   22:09   0:00 grep dispatch

Setting up Mysql

Connect to the Mysql database using your root user account and any password that you may have set for the account)

$ mysql -u root

Once you have connected to the database server, create a database for the Collaboa instance you wish to install, and set grant permissions accordingly. The below example assumes you wish to create a database instance called “collaboa_mysite”, with database user called “mysite” and password “mypass”. Replace these values with suitable choices for your own install.

$ mysql -u root

mysql> create database collaboa_mysite;
Query OK, 1 row affected (0.00 sec)

mysql> grant all on collaboa_mysite.* to 'myuser'@'localhost' identified by 'mypass';
Query OK, 1 row affected (0.00 sec)

mysql> quit
Bye