Redmine

h1. HowTo install Redmine in Apache Tomcat

As I'm running an Apache Tomcat Server already, I wanted to run redmine in it with Jruby, so I won't have to manage a mongrel/passenger setup.

It was much easier than I though, and works very well with Redmine version 0.8.0 and 0.8.6 on Ubuntu Karmic with the tomcat6 package available there.

*There is a problem on 0.8.7 not resolved yet! see http://www.redmine.org/issues/4276*

h2. Prerequisites and assumptions

Assumption is you have a Redmine install that works in plain ruby, meaning it's working with 

@./scripts/server -e productionq@. If not, check the normal installation docs first first!

I'm using a socket connection to a mysql server runing on the same machine as the Tomcat application server.

There might be some extra steps (e.g. configuring jdbc) necessary for a mysql connection via network.

It's also assumed you already have a Tomcat application server installed and running - If you haven't and don't know how to do it, you'll most likely run Redmine the default way with plain ruby.

Still, for Redmine developers  not too familiar with the Java platform but still willing to test Redmine here, I've added section below on how to setup and run a tomcat server.

h2. Install the necessary tools

* The Jruby binary (probably just for testing, not used in the deployment? I did not yet uninstall it and test if things still work, but I think they will)

** aptitude install jruby1.2 

* Go into the redmine directory

** @cd redmine-VERSION@

* Test running Redmine manually outside the Tomcat Servlet container - just to make sure it works(database, etc.) before deploying it in tomcat: 

** @jruby ./script/server -e production@

* Install warbler gem - a tool to package rails applications as Java web application .war files:

** @gem install warbler@

h2. Building the .war file

The .war file is a web application package - the standard way of packaging applications to be deployed in a Java servlet container.

* Run warble in configuration mode:

** @warble config@ - or if warble is not in your path like in my setup: @~/.gem/ruby/1.8/bin/warble config@

* Edit the warbler config:

** @vim config/warble.rb@

* change line beginning with @config.dirs...@ to look like this:

** @config.dirs = %w(app config lib log vendor tmp extra files lang)@

* Starting with Redmine 0.8.7, you also need to create 

* Run warble again (without config):

** @warble@ - or if warble is not in your path like in my setup: ~/.gem/ruby/1.8/bin/warble

You should have a file called @redmine-VERSION.war@ in the redmine directory now.

h2. Deploy the web application and Enjoy

Place the redmine war file into your tomcat webapps directory:

* @cp redmine-VERSION.war $TOMCAT_HOME/webapps/redmine.war@

Redmine should be running on http://your-tomcat-host.name:8080/redmine - likely you'll have to adjust hostname and port.

h2. Links that helped me to achieve this:

* http://musingsofaprogrammingaddict.blogspot.com/2008/11/redmine-on-jruby-and-glassfish.html

* http://www.digitalsanctum.com/2007/07/24/jruby-deploying-a-rails-application-on-tomcat/

h2. Tomcat setup

As said above, usually you will have a tomcat already running or at least know how to install it if you read this Howto. But for people willing to play with this for other reasons (e.g. Redmine developers trying to reproduce bugs :) ), here some words about installing tomcat:

* Install a Java 6 JDK - download from sun or with a package from you linux distribution, on Ubuntu, that is: 

** @apt-get install openjdk-6-jdk@

* Download Tomcat, for example from a location mentioned at http://tomcat.apache.org/download-60.cg - for example:

** @wget http://apache.autinity.de/tomcat/tomcat-6/v6.0.20/bin/apache-tomcat-6.0.20.tar.gz@

* Unpack the archive

** tar xvfz apache-tomcat-6.0.20.tar.gz

* You'll have a directory (referred to as TOMCAT_HOME in the deployment step above), got into it, and run tomcat:

** @sh bin/startup.sh@

* Test if tomcat is running by checking http://your-tomcat-host.name:8080

That's it, you're ready to deploy redmine in this Tomcat server!