Thursday, August 25, 2011

Migrating redmine and subversion to Mac OS X 10.7

I've been meaning to write up an article on setting up redmine and subversion on Mac OS X 10.6 - mostly to aid my own memory in case I need to do it again, but also for anyone else who might want to do it. When I first set these things up they had to be built from source (along with their dependencies), and then configured from the ground up. Thankfully now lots of the required components are part of Mac OS X, so the process is much, much simpler.

Last week the Mac Pro I've been running as a server failed (suspected dud power supply), and while it's out for repair I've had to shift the redmine and subversion installations onto an alternate server to keep things moving. Mac OS X 10.7 is now out too, so I'm migrating the installation from 10.6, and updating some things along the way.

Why would you want do this? If you're into developing software you need source control. There are lots of other options, but subversion suits my workflow, and allows previous versions of source to be pulled, and allows work to be done and synchronised from multiple computers. I'm in a development team of 1, so I don't need multi-user features, but it's for that too. Redmine is a tool that can do a heap of stuff - I just use it for logging 'issues' with the software I'm working on (bugs, new feature requests...). I find myself using it as a sort of to-do list that I can access and update over the web. It runs using ruby on rails, so it's a good excuse to look at that too.

Starting conditions:

I have had redmine and subversion running under Mac OS X 10.6.8 on a Mac Pro. I'm migrating to an iMac running Mac OS X 10.7.2, with all updates current to December 12, 2011. Developer tools are installed, but there's nothing yet in /usr/local/. apache2 is installed on Mac OS X by default.

Here's some terminal output showing versions of relevant software components. You can see that mysql is not installed, and no ruby gems are installed:

server:~ user$ ruby --version
ruby 1.8.7 (2010-01-10 patchlevel 249) [universal-darwin11.0]
server:~ user$ gem --version; rake --version; rails --version;
1.3.6
rake, version 0.8.7
Rails is not currently installed on this system...
server:~ user$ mysql --version
-bash: mysql: command not found
server:~ user$ gem list

*** LOCAL GEMS ***

server:~ user$

Before we start, some of the more useful websites I've consulted are:

The Redmine Install wiki.

The Redmine Mac OS X - Snow Leopard installation notes.

A page describing moving redmine from one server to another, and a page with some info about installing MySQL on Mac OS X 10.6.

I'll break this into 4 parts: mysql (required for redmine), redmine, subversion, and configuring apache.

Installing MySQL:

Mac OS X doesn't come with MySQL, although I think the Server version does. Good installers are provided at www.mysql.com. I chose to install from a disk image using a GUI installer. The file I downloaded is mysql-5.5.18-osx10.6-x86_64.dmg.

Here are the steps:

  • install the mysql binary
  • install the startup item
  • install the prefPane in /Library/PreferencePanes

    It used to be necessary to set permissions on the startup item to get the prefPane to work. The code to do it is provided here for completeness, but with this version of mysql I found it was not necessary.

    In a Terminal:

    sudo chown -R root:wheel /Library/StartupItems/MySQLCOM

  • use the preference pane to start/stop mysql. Hopefully you get some green text that says "The MySQL Server Instance is running".

  • add mysql to the PATH. Do this by adding the following line to ~/.bashrc:

    export PATH=${PATH}:/usr/local/mysql/bin

    Then start a new terminal to load ~/.bashrc, or type

    source ~/.bashrc

    at the command line. You can check that mysql is installed correctly by running it (as superuser).

Installing Redmine

There are lots of docs around on how to do this - although there are some subtle differences between different operating systems. They tend to end at 'testing the development setup using webrick', which is not intended for production use. Here I'll describe setting up redmine to run through apache and be world visible.

I started by downloading the latest stable version:

svn co http://redmine.rubyforge.org/svn/branches/1.2-stable redmine-1.2

On Mac OS X the root of the web server is at /Library/WebServer/Documents, so a good place for redmine is in /Library/WebServer/Documents/redmine-1.2, with a symlink to /Library/WebServer/Documents/redmine. This is a restricted access directory, so all the terminal commands will need to be run as superuser. The following terminal commands assume you've cd'd into the redmine directory.

Configure database access

Copy config/database.yml.example to config/database.yml

cp config/database.yml.example config/database.yml

Edit config/database.yml, removing all but the 'production' section. In my case, I've edited it to look like this:

production:
  adapter: mysql
  database: redmine
  host: localhost
  username: redmine
  password: redmine_pass

Create the log file if necessary:

touch log/production.log

Change permission for the log file [may need to be created first]:

sudo chmod 0666 log/production.log

Change the owner for the files directory, where redmine will save files:

sudo chown -R _www files

NOTE: If migrating an existing redmine installation, the contents of the files directory need to be copied across, and the appropriate permissions set.

Create the mysql database for redmine

Run mysql as superuser

sudo mysql

Run the following commands in mysql to create the database. Note that the values are the same as those in config/database.yml

create database redmine character set utf8;
create user 'redmine'@'localhost' identified by 'redmine_pass';
grant all privileges on redmine.* to 'redmine'@'localhost';
exit

Again, if you're migrating an existing redmine installation, the database content needs to be copied across. To do this the mysql database needs to be 'dumped' from the old server with the following command (the password will be requested by mysql):

mysqldump -u redmine -p redmine > /location/of/dump/file.sql

The dumped database can be reloaded on the new server:

mysql -uredmine -p redmine < /location/of/dump/file.sql

Set up the necessary Ruby gems

i18n

sudo gem install -v 0.4.2 i18n

rails

I started by installing the v 2.3.5 version, but had some issues and ended up going to v 2.3.11 (see below).

sudo gem install -v 2.3.5 rails

mysql

Redmine needs this to access the mysql database where it stores its stuff. I started by not specifying a version number, which installed 2.8.1. If you read on you'll find that this is a problem, and version 2.7 is the magic version.

export ARCHFLAGS="-arch x86_64"
sudo gem install --no-rdoc --no-ri mysql -- \
    --with-mysql-dir=/usr/local/mysql \ 
    --with-mysql-config=/usr/local/mysql/bin/mysql_config

In order to ensure ruby can access the mysql libraries execute the following (first check the paths are relevant for your versions). This assumes your current directory is /usr/local/mysql/lib.

sudo install_name_tool -change libmysqlclient.18.dylib \
    /usr/local/mysql/lib/libmysqlclient.18.dylib \
    /Library/Ruby/Gems/1.8/gems/mysql-2.8.1/lib/mysql.bundle

You can then check things are OK by running irb and checking that mysql can be accessed:

> irb
require 'mysql'
true
exit

If you see 'true', you're good to go.

Versions... here's where the fun stuff begins...

The next thing to do is go into the redmine directory, and run a rake command to generate the session store. This is to generate a session store secret. Not sure exactly what that means, but it sounds important.

> sudo rake generate_session_store

Now, if you're lucky a heap of text will fly by, and there are no errors. More likely there will be some problems... Here's what I got:

Missing the Rails 2.3.11 gem. Please `gem install -v=2.3.11 rails`, update your \
RAILS_GEM_VERSION setting in config/environment.rb for the Rails version you do \
have installed, or comment out RAILS_GEM_VERSION to use the latest version installed.

So, I installed the 2.3.11 version.

sudo gem install -v 2.3.11 rails

Now, try again...

sudo rake generate_session_store

And once more, crashed and burned:

WARNING: 'require 'rake/rdoctask'' is deprecated.  Please use 'require 'rdoc/task' (in RDoc 2.4.2+)' instead.
    at /Library/Ruby/Gems/1.8/gems/rake-0.9.2.2/lib/rake/rdoctask.rb
WARNING: 'task :t, arg, :needs => [deps]' is deprecated.  Please use 'task :t, [args] => [deps]' instead.
    at /Users/wpowell/Development/redmine-1.2/lib/tasks/email.rake:170

I looked around and concluded that the version of rake was too new, so downgraded:

sudo gem uninstall rake

Select gem to uninstall:
 1. rake-0.8.7
 2. rake-0.9.2.2
 3. All versions
> 2
Successfully uninstalled rake-0.9.2.2

So now we're running rake 0.8.7, let's have another go...

sudo rake generate_session_store

Woo Hoo! Seems to have worked. Next step is to migrate the database:

sudo RAILS_ENV=production rake db:migrate

And there's another error...

rake aborted!
Object is not missing constant Issue!

(See full trace by running task with --trace)

Cryptic. Running the full trace didn't really help. This error has bugged me in the past, and I eventually figured out that it's related to the version of the mysql gem. So, uninstall version 2.8.1 and install 2.7...

sudo gem uninstall mysql
export ARCHFLAGS="-arch x86_64"
sudo gem install -v 2.7 --no-rdoc --no-ri mysql -- \
    --with-mysql-dir=/usr/local/mysql \
    --with-mysql-config=/usr/local/mysql/bin/mysql_config

Again, make sure ruby can access the mysql libraries...

sudo install_name_tool -change libmysqlclient.18.dylib \
    /usr/local/mysql/lib/libmysqlclient.18.dylib \
    /Library/Ruby/Gems/1.8/gems/mysql-2.7/lib/mysql.bundle

Now let's try that rake command again.

sudo RAILS_ENV=production rake db:migrate

...lots of printing out... looks promising. Now test with the WEBrick web server built into rails

ruby script/server webrick -e production

Open a web browser to http://127.0.0.1:3000... and it works!!

Moving to apache

This can be covered in another post...