After more than a year of using Redmine to help us manage our projects it was time to upgrade. Redmine helps us manage our bug lists, wish lists, and to do lists. It helps us communicate with our clients effectively and efficiently using a web based media in a consistent format that is easy to use for both our developers and our clients. However, during the past year there have been several changes including the significant upgrades that came out in v9.x some months back. Our busy schedule kept us from upgrading as each new release came out, and sadly we had fallen far behind. This past weekend we decided it was time to upgrade. The notes below record some of the problems we ran into and outlines how we resolved them. If you are using Redmine for your own projects we hope this guide will help walk you through a major version update of your own.
These are Cyber Sprocket’s notes from our upgrade. For more information you may want to visit the official documentation site.
The environment we were running before upgrading to Redmine 9.3:
- Redmine 8.6
- Apache 2.2.7
The first thing we ALWAYS do before upgrading a system is to store a local copy of the database and the source code. In order to make the archives as small as possible we post a note on the system that Redmine will be offline and at the posted time remove all the session “crud” that has built up. The process includes a mysql data dump, a file removal, and a tarzip.
- Go to the directory ABOVE the redmine root directory:
cd /<redmine-root-dir>; cd ..;
- Dump MySQL Redmine data:
mysqldump –user=<your-redmine-db-username> -p <your-redmine-databasename> > redmine_backup.sql
- Remove the session files:
rm -rf <redmine-directory>/tmp/sessions/*
tar cvfz redmine-backup.tgz redmine_backup.sql ./<redmine-directory-name>
We realized after some back & forth that our RoR installation needed to be upgraded. Redmine 9.3 require Ruby 1.8.6 or 1.8.7 (we had 1.8.6 luckily) with Rails 2.3.5 (which we needed to upgrade) and Rack 1.0.1 (which we never touched).
gem install rails -v=2.3.5
We could not perform a simple svn update since we are on an 8.X branch. A new svn checkout was necessary. We opted to move our old Redmine install to a different path and do the checkout in our original location:
svn checkout http://redmine.rubyforge.org/svn/branches/0.9-stable/ /redmine
Later version of Redmine (even 8.X versions beyond 8.6) require a secret key in order for the session system to work. If you don’t have this you can’t login. After much trial & error we found that the following command WILL WORK if you have the latest Redmine source (Fetching 9.3) and the latest version of Rails (Updating Rails). There is not file named config/initializers/session_store.rb in the code repository, it is created by the following rake command:
Updating The Database
The database then needed to be migrated:
rake db:migrate RAILS_ENV=production
Database Upgrade Errors : Migrating Member_Roles and Groups
While performing the database update we immediately ran into a couple of errors about a table already existing. Turns out a simple renaming of the tables fixed the problem, no apparent harm done.
The error message was:
Mysql::Error: Table 'member_roles' already exists:
The fix was as simple as logging into MySQL from the command line and renaming the table:
mysql> rename table member_roles to member_roles_saved mysql> rename table groups_users to groups_users_saved
Switching from CGI to FCGID
It turns out that RoR does not play well with plain ol’ CGI processing via Apache when running Rails v2.3.5. We ended up having to upgrade our Apache server to enable mod_fcgid and tweaking our new Redmine install to use that. We started by following this excellent guide go running Redmine on Apache. Below are our notes about this process to help save you some time:
- Do not install fcgi, instead use Apache’s mod_fcgid
- chmod 755 /var/log/httpd so fgcid can run from Apache and access the socks directory it creates there
- Modify <redmine-directory>/public/.htaccess to prevent looping with mod_rewrite
“Official Apache mod_fcgid”:http://httpd.apache.org/mod_fcgid/ this is the Apache version, seems newer and we had more luck with this than the Coremail hosted version below.
Fetch the code
cd /usr/local/src/ wget http://apache.mirrors.hoobly.com/httpd/mod_fcgid/mod_fcgid-2.3.5.tar.gz tar zxvf mod_fcgid.2.3.5.tgz cd mod_fcgid.2.3.5
Configure and Install
./configure.apxs make make install
chmod 755 /var/log/httpd service httpd restart
Install Ruby Gem fcgi
You will need to tell Ruby to work with fcgi for this to work:
gem install fcgi
Errors Installing fcgi gem
If you see this error:
Could not create Makefile due to some reason, probably lack of necessary libraries and/or headers. Check the mkmf.log file for more details. You may need configuration options.
You probably need the fcgi development kit. Get it from here, build it & install it… THEN do the gem install fcgi again.
You may end up with looping with mod_rewrite if you had a CGI version installed first. We commented out the non-fcgid lines and that kept things running smoothly.
Comment all the lines for the Rewrite rules for the dispatcher except the FCGI rule for fcgid
#<IfModule mod_fastcgi.c> # RewriteRule ^(.*)$ dispatch.fcgi [QSA,L] #</IfModule> #<IfModule mod_fcgid.c> RewriteRule ^(.*)$ dispatch.fcgi [QSA,L] #</IfModule> #<IfModule mod_cgi.c> # RewriteRule ^(.*)$ dispatch.cgi [QSA,L] #</IfModule>
Getting Errors With FCGID?
This is a very common error. For some reason Ruby + mod_fcgid do not always play well with each other. We have two near-identical servers running CentOS 5, Apache 2.2.x, and the same exact versions of Ruby + Rails + gems installed. Yet on one server Redmine works fine. On the other we get this:
undefined method `env_table’ for nil:NilClass
The “magic pill” seems to be running Passenger. While we didn’t believe this at first since we got it to work fine on our development server, it turns out that there are some gremlins buried deep within the bowels of Ruby & mod_fcgid. These few steps fixed the problem on our production server:
gem install passenger passenger-install-apache2-module
Edit the httpd.conf file and add these lines (check your paths that Passenger gives you during the install – they may be different on your server):
LoadModule passenger_module /usr/local/lib/ruby/gems/1.8/gems/passenger-2.2.11/ext/apache2/mod_passenger.so PassengerRoot /usr/local/lib/ruby/gems/1.8/gems/passenger-2.2.11 PassengerRuby /usr/local/bin/ruby
service httpd restart
Test your Redmine install.
If you have problems check the log files in your Redmine installation directory, such as ./log/production.log. You may also want to check your Apache log files, assuming you’ve set those up. To log Apache messages you need to have an ErrorLog statement in your httpd.conf file that tells Apache where you want your log file written (normally /usr/local/apache/logs/redmine-error.log).