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...
