Tuesday, December 2, 2008

Bookmark and Share
Redmine is a project management software written in Ruby. It offers a lot of interesting features such as an issue tracker, wiki functionality and news feeds. This post will show up the steps required to install Redmine and run in it on JRuby using Glassfish application server.

This tutorial is based on the following assumptions:
  • Ubuntu is being used as OS
  • Java is installed on your system
  • Glassfish is installed (%GLASSFISH_HOME% will be used in the following to refer to the installation directory)
  • All downloads go to /tmp

Install JRuby

In order to run Redmine, a Ruby runtime has to be installed first. We will use JRuby 1.1.4 (the current version at the time of this writing - 1.1.5 - didn't work, probably due to this bug). Download it and add JRuby to your path as follows:
$ wget dist.codehaus.org/jruby/jruby-bin-1.1.4.tar.gz
$ cd /opt
$ sudo tar -xzvf /tmp/jruby-bin-1.1.4.tar.gz
$ sudo ln -s jruby-1.1.4 jruby
$ export PATH=$PATH:/opt/jruby/bin
Verify that JRuby is set up properly by issuing:
$ jruby -v
This should yield in:
jruby 1.1.4 (ruby 1.8.6 patchlevel 114) (2008-08-28 rev 7570) [i386-java]

Download required gems

Having JRuby up and running, we need to install the ActiveRecord JDBC MySQL adapter for Rails. Furthermore it is recommended to install JRuby's Open SSL support as well. Finally, we need Warbler, which will allow us to package the Redmine application as a WAR archive. Using the RubyGems package manager, this is easy:
$ sudo gem install jruby-openssl activerecord-jdbcmysql-adapter warbler
All required dependent gems (such as activerecord-jdbc-adapter) will automatically be downloaded by RubyGems.

Install and set up MySQL database server

Next, the database to be used by Redmine needs to be set up. We will be using MySQL, as it is a very common companion for RoR apps, though other database servers should do the trick as well.

Install the server:
$ sudo apt-get install mysql-server
Login into MySQL:
$ mysql -u root -p %YOUR_PASSWORD%
Create a database:
mysql> CREATE DATABASE redmine_production character set utf8;
Create a database user:
mysql> GRANT ALL ON redmine_production.* TO 'redmine'@'localhost' IDENTIFIED BY 'redmine';
Repeat the latter two steps for schemas redmine_test and redmine_development and leave the MySQL shell.
mysql> exit

Create data source in Glassfish

In order to set up a MySQL based data source in Glassfish, the server has to be provided with the MySQL JDBC driver. Ensure that Glassfish is stopped for the following. So let's download the driver, un-tar it and copy it into the server's lib dir:
$ wget
dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-5.1.7.tar.gz/from/http://sunsite.informatik.rwth-aachen.de/mysql/
$ tar -xzvf mysql-connector-java-5.1.7.tar.gz
$ sudo cp /mysql-connector-java-5.1.7/mysql-connector-java-5.1.7-bin.jar %GLASSISH_HOME/lib/
Now start up Glassfish:
$ %GLASSISH_HOME/bin/asadmin start-domain domain1
Create a connection pool and a JDBC resource (if you prefer a more visual way of doing such things, help can be found here):
$ %GLASSISH_HOME/bin/asadmin create-jdbc-connection-pool
--datasourceclassname
com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource --restype
javax.sql.DataSource --property
"User=redmine:Password=redmine:URL=jdbc\:mysql\://localhost\:3306/redmine_production"
jdbc/RedminePool
$ %GLASSISH_HOME/bin/asadmin create-jdbc-resource --connectionpoolid jdbc/RedminePool jdbc/Redmine

Install and set up Redmine

Now it's time to install Redmine itself (refer to the official installation guide for further information). So download and extract the archive:
$ wget rubyforge.org/frs/download.php/39477/redmine-0.7.3.tar.gz
$ tar -xzvf redmine-0.7.3.tar.gz
Create a new database environment "production_setup" and the database config file:
$ cp config/environments/production.rb config/environments/production_setup.rb
$ cp config/database.yml.example config/database.yml
Edit config/database.yml:
production:
  adapter: jdbc
  jndi: jdbc/Redmine

production_setup:
  adapter: jdbcmysql
  database: redmine_production
  host: localhost
  username: redmine
  password: redmine
  encoding: utf8

development:
  adapter: jdbcmysql
  database: redmine_development
  host: localhost
  username: redmine
  password: redmine
  encoding: utf8

test:
  adapter: jdbcmysql
  database: redmine_test
  host: localhost
  username: redmine
  password: redmine
  encoding: utf8
The "production" environment is configured to use the data source, which we previously created within the Glassfish server. No credentials are stored here, as they are part of the connection pool's configuration. Note the special environment "production_setup" which we'll use now to initialize the database:
$ rake db:migrate RAILS_ENV="production_setup"
$ rake redmine:load_default_data RAILS_ENV="production_setup"
Now we can test the application using Webrick:
$ jruby script/server -e production_setup

Package and deploy Redmine

Running the application on Webrick is fine for testing purposes, but now let's deploy Redmine on Glassfish. For this target, the Warbler gem comes into play. It takes a Rails application and creates a WAR archive from it. Besides the application itself, JRuby and all required gems are packaged into the archive as well. Therefore, this WAR is fully self-contained and can be deployed on every web container or application server. First, we have to create the Warbler configuration:
$ warble config
This will create the file config/warble.rb. Edit this file, find the line beginning with "config.dirs ..." and replace it with the following:
config.dirs = %w(app config lib log vendor tmp extra files lang)
This will cause the named directories to be packaged into the resulting WAR. Find the line beginning with "#config.gems += " and uncomment it, allowing for the gems active-record-jdbcmysql-adapter and jruby-openssl to be packaged into the WAR as well.

Having configured warbler, the web archive can be created. Go to the application's root dir and enter:
$ warble
The resulting WAR file can now be deployed to the app server. Either do this within the admin console or just by copying it to Glassfish's auto deploy folder:
$ cp redmine-0.7.3.war %GLASSFISH_HOME%/domains/domain1/auto-deploy
Upon success, Redmine can be accessed at http://localhost:8080/redmine-0.7.3. Click "Sign in" in the upper right, log in using "admin"/"admin" as user/password and you should see your personal Redmine page as depicted below.

Typically, you would now create a project or other user accounts, which can be done under "Administration".

14 comments:

MadMax-007 said...

THis is a great help for installing redmine but all visitors BE AWARE i spent 68 hours on all kinds of examples and helppages when i found out that jruby 1.1.5 is crap! use 1.1.6RC1 and it works within 10 minutes.

with 1.1.5 you get strange errors on all database-related setting

Gunnar Morling said...

JRuby 1.1.5 gave me some trouble, too. Therefore I used JRuby 1.1.4 for this post, as described in the "Install JRuby" section.

Btw., which version of Redmine did you use? If time allows, I'll update the post for the current version.

Greets, Gunnar

MadMax-007 said...

Hi Gunnar,
When you have time please update this page regarding the "Edit config/database.yml: "
production:
adapter: jdbc
jndi: jdbc/Redmine

production_setup:
[space][space]adapter: jdbcmysql
[space][space]database:
[space][space]redmine_production
[space][space]host: localhost
[space][space]username: redmine
[space][space]password: redmine
[space][space]encoding: utf8

alle entries need a double space before the first word like:

production_setup:
adapter: jdbcmysql
database: redmine_production
host: localhost
username: redmine
password: redmine
encoding: utf8

Compiling will fail if you don't do that.

Br Roel

MadMax-007 said...

hmz, wrong example edited ;-(

realize said...

Thank Gunnar Morling.
Your blog is very helpful to me too. I have to find opensource for SCM.
I chose redmine because I'm familiar with java so I can run redmine with JRuby.
First time, I can't see 1.1.6 on this page. I thought 1.1.6 have not released yet then I instead used JRuby 1.1.5, and I got the same problem.
I trid to find JRuby 1.1.6 again and found 1.1.6 release at this link here.
The download structure was changed to early version.
It's work. Thank again.

Gunnar Morling said...

@MadMax

Thanks for the pointer; I corrrected this. Obviously this was an issue with the blogspot software, as it removed the leading spaces.

Greets, Gunnar

csligon said...

I have noticed that viewing diffs under the repository tab of a project does not work when running redmine as a war file. I have not been able to fix this issue yet.

MadMax said...

Hi Gunnar,

I just tried to install the latest redmine version 0.9.2 (2010-02-07).

for everyone who wants to update or install this redmine version.
1. Just follow this thread until the line "Now we can test the application using Webrick: "
2. then follow the instructions on http://www.redmine.org/wiki/redmine/RedmineUpgrade till step 5. don't do step 5!
3. do warble config
4. edit config/warble.rb
5. This will create the file config/warble.rb. Edit this file, find the line beginning with "config.dirs ..." and replace it with the following:

config.dirs = %w(app config lib log vendor tmp extra files lang)
6. Find the line beginning with "#config.gems += " and uncomment it
7. REPLACE THIS LINE WITH:
"config.gems += ["activerecord-jdbcmysql-adapter", "jruby-openssl","rack"]"
8. create the WAR
9. deploy in Glassfish

I just tested it with Glassfish V3. final and it works.
I only had problems with the rack gem, that s why you need to update the warble.rb file.

tin said...

Thanks for this post. I am new to Ruby. I liked redmine a lot and wish to add few plugins/features to it. Since I am comfortable with Java, can I make use of the setup explained here to write new features to redmine in Java language?

Gunnar Morling said...

@tin

That's really an interesting question. You can call Java code from within Ruby programs, therefore one could think of a Redmine plug-in that wraps some Java functionality.

But I think that's a pretty uncommon approach and actually I'd recommend to spend some time to get used with Ruby and implement Redmine plug-ins in Ruby.

v said...

Thank you for this article, very useful!

I've used redmine 0.9.1, 1.0 RC with PostgreSQL and it worked flawlessly on JRuby. However, when I've tried to upgrade Redmine to 1.0.3, and JRuby 1.5.5, there was an error in logs.

ActiveRecord::StatementInvalid (ActiveRecord::JDBCError: ERROR: column "issues.id" must appear in the GROUP BY clause or be used in an aggregate function
Позиция: 78: SELECT COUNT(*) AS count_all, tracker_id AS tracker_id FROM (SELECT DISTINCT "issues".id FROM "issues" LEFT OUTER JOIN "projects" ON "projects".id = "issues".project_id LEFT OUTER JOIN "issue_statuses" ON "issue_statuses".id = "issues".status_id LEFT OUTER JOIN "trackers" ON "trackers".id = "issues".tracker_id WHERE (((projects.id = 2 OR (projects.lft > 7 AND projects.rgt < 10))) AND issue_statuses.is_closed='f') AND (((projects.status=1 AND projects.id IN (SELECT em.project_id FROM enabled_modules em WHERE em.name='issue_tracking')) AND (1=0 OR projects.is_public = 't' OR projects.id IN (6,4,3,1,2,5)))) GROUP BY tracker_id ) count_all_subquery):
gems/gems/activerecord-jdbc-adapter-1.0.2-java/lib/arjdbc/jdbc/adapter.rb:178:in `execute'
gems/gems/activerecord-jdbc-adapter-1.0.2-java/lib/arjdbc/jdbc/adapter.rb:267:in `select'
gems/gems/activerecord-jdbc-adapter-1.0.2-java/lib/arjdbc/jdbc/adapter.rb:197:in `jdbc_select_all'
app/controllers/projects_controller.rb:158:in `show'
file:lib/jruby-rack-1.0.3.jar!/vendor/rack-1.2.1/rack/head.rb:9:in `call'
file:lib/jruby-rack-1.0.3.jar!/vendor/rack-1.2.1/rack/methodoverride.rb:24:in `call'
file:lib/jruby-rack-1.0.3.jar!/vendor/rack-1.2.1/rack/lock.rb:11:in `call'
file:lib/jruby-rack-1.0.3.jar!/rack/adapter/rails.rb:36:in `serve_rails'
file:lib/jruby-rack-1.0.3.jar!/rack/adapter/rails.rb:41:in `call'
file:lib/jruby-rack-1.0.3.jar!/jruby/rack/rails.rb:180:in `call'
file:lib/jruby-rack-1.0.3.jar!/rack/handler/servlet.rb:19:in `call'
:1

To fix it, define a specific version of activerecord-jdbcpostgresql-adapter in warble.rb:
config.gems["activerecord-jdbcpostgresql-adapter"] = "0.9.7"
It doesn't work with version 1.0.2 of this adapter.

Hope this will help somebody, if he read this article and stuck with the same problem as I!

Anonymous said...

v, I faced a problem like you this morning: have a working copy of redmine 1.0.1 and after upgrading to 1.0.3 it doesn't work.

Fortunately I think I've solved it: you must use the same gems for 1.0.3 that for 1.0.1. In my case they are:

activerecord-jdbc-adapter -> 0.9.7
rack -> 1.0.1

And don't forget to keep the database.yml settings.

Bye

Anonymous said...

Terima kasih

Chris said...

I like the valuable information you provide in your articles. I will bookmark your blog and check again here frequently. I am quite certain I will learn lots of new stuff right here! Good luck for the next!

Visit us:
job interview question
Recognized by many