Install ruby

Ruby installation depends on your operating system. Please visit http://www.ruby-doc.org/ or use a search engine for more details about Ruby installation on your system.

On Debian based systems (Debian, Ubuntu, Mepis, etc.):

apt-get install ruby libruby rdoc

On Fedora Core yum is your friend. Assuming a minimal server installation of Fedora Core, you should type in the following to install the required RPMs:

sudo yum install ruby ruby-irb ruby-libs ruby-rdoc ruby-devel readline

Optional RPMs include the following:

• subversion subversion-devel subversion-ruby (required if you want Retrospectiva’s source browser integration)
• mysql-devel*, postgres-devel* OR sqlite3-devel* depending on your database server. I assume you have your database server installed and configured already.

Note: I would advise against installing the ruby-mysql, ruby-postgres or ruby-sqlite3 RPMs. We will install the relevant Ruby libraries as Ruby Gems instead later. Of course, if you prefer RPMs to Ruby Gems (I don’t know why you would), then you can use them, I don’t know of any issues, except from a maintenance consistency perspective. The exception here is the subversion-ruby RPM listed above, which presently does not have a Ruby Gem available to my knowledge, although you can create one from scratch.

Install RubyGems

Download RubyGems from http://www.rubygems.org/ (try http://rubyforge.org/frs/?group_id=126 for the direct download) then run as root:

tar -zxvf rubygems-x.x.x.tgz
cd rubygems-x.x.x.tgz
ruby setup.rb

That’s it!

Notes:

• You will also need ruby1.8-dev package to be able to install RubyGems on Ubuntu 6.
• Do NOT install the RubyGems DEB package from apt repositories on Debian based Systems (Debian, Ubuntu, etc.). The package is broken, please follow the installation instructions above instead.

Install ruby libraries

You will need:

• mysql, postgres, etc. – depends on the database you would like to use
• readline – readline support is always a good idea
• iconv – for unicode support

Installation can either be done by rubygems, calling (as root):

gem install mysql
gem install readline
gem install iconv

Notes: For FC6 users, the mysql gem line should be:

gem install mysql -- --with-mysql-include=/usr/include/mysql --with-mysql-lib=/usr/lib/mysql

or, again, by using the OS package manager, eg:

apt-get install libmysql-ruby libreadline-ruby libiconv-ruby

Subversion support

If you would like to use the Retrospectiva “Code browser” you will need SVN bindings for Ruby.

On Debian Etch and Ubuntu 6 these can be installed by calling (as root):

apt-get install libsvn-ruby

On OS X

sudo port install subversion-rubybindings

On Debian Sarge you need to use the backported package. Please download it from http://www.backports.org.

Install rails

Install rails by executing (as root):

gem install rails

For more information please see http://www.rubyonrails.org/down

Checkout Retrospectiva from SVN

First of all, please make sure that subversion is installed. Change to the directory where Retrospectiva is going to be installed and checkout the program and rename the directory, example:

cd /var/www
svn co http://retrospectiva.googlecode.com/svn/branches/1-0 retrospectiva
cd retrospectiva

If you want to use the experimental development version instead, use:

svn co http://retrospectiva.googlecode.com/svn/trunk retrospectiva_dev

Configure retrospectiva

Create a database and a database user for Retrospectiva. Login to the database console or interface and execute the following SQL code (please set your own password):

CREATE DATABASE IF NOT EXISTS retrospectiva;
GRANT ALL PRIVILEGES ON retrospectiva.* 
  TO "retrospectiva"@"localhost" 
  IDENTIFIED BY "xxxxxxxxxxx";

Go to the config/ directory of your Retrospectiva installation and rename the database.yml.todo file to database.yml

cd config
mv database.yml.todo database.yml

Now open the database.yml with a text editor and set the database, username and password names according to your database settings in the production section. (If you get “No such file or directory – /var/run/mysqld/mysqld.sock” errors later, you can remove all the lines that start with “socket:”)

Load database schema and initial content

Go to your Retrospectiva root directory and type:

rake RAILS_ENV=production db:retro:load

If you set your database.yml correctly, the database will be filled with the inital schema and content.

NOTE: If you encounter:

wrong number of arguments (1 for 0)

run the previous command with ‘—trace’ appended to the end. You will get an output like this:

(in /the/path/to/your/retrospectiva)
** Invoke db:retro:load (first_time)
** Invoke environment (first_time)
** Execute environment
rake aborted!
wrong number of arguments (1 for 0)
/the/path/to/your/retrospectiva/vendor/plugins/factory_hashcash/init.rb:10:in `load_helpers'
/the/path/to/your/retrospectiva/vendor/plugins/factory_hashcash/init.rb:10:in `evaluate_init_rb'
/usr/lib/ruby/gems/1.8/gems/rails-2.0.2/lib/rails/plugin.rb:79:in `evaluate_init_rb'
/usr/lib/ruby/gems/1.8/gems/activesupport-2.0.2/lib/active_support/core_ext/kernel/reporting.rb:11:in `silence_warnings'
...
...
...
/usr/lib/ruby/gems/1.8/gems/rake-0.8.1/lib/rake.rb:1881:in `run'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.1/lib/rake.rb:1948:in `standard_exception_handling'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.1/lib/rake.rb:1878:in `run'
/usr/lib/ruby/gems/1.8/gems/rake-0.8.1/bin/rake:31
/usr/bin/rake:16:in `load'
/usr/bin/rake:16

If you see ‘rails-2.0.2’ around line 9, then that means that you have Rails version 2.0.2 installed, in which case you will need to install the latest trunk version of Retrospectiva instead.

To do so, either run the following command via ssh on your server or run it locally and then ftp to your server.

svn export http://retrospectiva.googlecode.com/svn/trunk retrospectiva

Once the ‘rake’ command is run successfully, you may continue with the installation.

Important!!!

Please make sure that the public/dispatch.fcgi and the public/dispatch.cgi files are executable by calling:

chmod +x public/dispatch.*

and also make sure that the config/runtime, attachments/, extensions/ and log/ directories are writable for the web-server user.

Example for those who plan to run Retrospectiva with a specific user/group (e.g.: www-data):

chgrp -R www-data config/runtime/
chgrp -R www-data log/
chgrp -R www-data attachments/
chgrp -R www-data tmp/
chgrp www-data extensions/

chmod -R g+w config/runtime/
chmod -R g+w log/
chmod -R g+w attachments/
chmod -R g+w tmp/
chmod g+w extensions/

Example for those who plan to run Retrospectiva with Webrick (or are not sure about setting user/group rights):

chmod -R +w config/runtime/
chmod -R +w log/
chmod -R +w attachments/
chmod -R +w tmp/
chmod +w extensions/

Start Retrospectiva

You can integrate Retrospectiva within your own web server, please see the Deployment page in the Retrospectiva Wiki for more information,

As a quick test, you can also use the built-in web-server “Webrick”. You can run it by calling:

ruby script/server -e production -p3000

Retrospectiva is now running, you can access your installation using a web-browser by entering http://use-your-server-name:3000.

To enter the administration environment login as ‘admin’ and use ‘password’ as password (please change this default password after successful login).

Note: for RSS feeds to be readable, you may need to go in the Admin page, click on Groups, and edit the Default group to have permissions to view the Blog

Tasks

To setup tasks (i.e. mail notifications) you need to create a (one single) cron job, that executes the retro_tasks script minutely. retro_tasks is a very resource-efficient script (e.g. it loads the rails environment only if necessary) that decides which tasks to run and when. All other parameters (time intervals, etc.) can be set up & viewed in the Administration interface of Retrospectiva.

To install a cron job, call crontab -e as the web-server user and paste the following line:

* *  * * *  RAILS_ENV=production ruby /path/to/retrospectiva/script/retro_tasks

Configure ExceptionNotifier

Add this to the end of your enviroment.rb:

ExceptionNotifier.exception_recipients = %w(your_email_adress@whatever.org)

Then you will get emails when an error on your server occurs.