Kete.net.nz: Documentation

Topic: Mac OS X Installing Required Software

Topic Type: Topic

Describes the steps necessary for installing Kete's required software on a Mac OS X host.

Originally written by Walter McGinnis, Kete Project Lead for Katipo Communications, Ltd.

Part of the Installation Guide

---

Note: This section covers both Mac OS X 10.4.11 (Tiger) and Mac OS 10.5.1 (Leopard). Referred to as 10.4 and 10.5 from here forward. Pay careful attention to what steps are marked for each

Install MacPorts

Follow the instruction at http://www.macports.org/install.php to install MacPorts on your system. Make sure you meet all the requirements and test it's working before continuing.

Install Required Software for Running Kete

So lets get installing. Run the followig from the console:

10.4: Tiger needs Ruby and RubyGems installed rom MacPorts, so you'll need to run this next command
10.5: Leopard includes Ruby and RubyGems already, so you can skip to the next command

$ sudo port install ruby rb-rubygems

10.x: Then for both systems, run

$ sudo port install git-core memcached nginx zlib unzip libxslt mysql5 +server

10.4: We can install the Ruby-Mysql adapter via MacPorts

$ sudo port install rb-mysql

10.5: We use the gem version of the Ruby-Mysql adapter

sudo env ARCHFLAGS="-arch i386" gem install mysql --with-mysql-config=/opt/local/bin/mysql_config5

(optional - enables conversion of uploaded HTML, Plain Text, PDF, and Microsoft Word documents to the description of the document)

$ sudo port install poppler poppler-data wv lynx

Installing the Rails framework

There are two options when it comes to installing Rails. The first is to install it on the ruby installation you setup above using port install. The more secure option is to use Ruby Enterprise Edition, a product from the same people that make mod_rails/Passenger (discussed at the bottom of this page). It's updated a lot more regularly than MacPorts updates their packages, which means it has more bug and security fixes. It's also optimized to run faster than a standard installation of Ruby. It requires a few extra installation steps, but it's well worth the effort.

Installing Rails on Debian installed Ruby

Install both rails (framework) and mongrel (server) that Kete will run on. You may encounter something like "could not find blah..." when running the following commands. Rubyforge and the gem mirrors can be flaky, just try again and it will usually come right.

$ sudo gem update --system

10.4: The gem update may have messed up the gem command. So we may have to make to make a slight adjustment in it to be compatible with 10.4 as outlined in this blog post.

With root privileges, open up /usr/bin/gem in a text editor. Add the line below, after the "require 'rubygems'" line and save:

require 'rubygems/gem_runner'

10.x: Then back to our installing of software...

$ sudo gem update
$ sudo gem install rails mongrel mongrel_cluster

Installing Rails with Ruby Enterprise Edition

The great thing about Ruby Enterprise Edition (refered to as REE) is that the installer does the installing of Ruby and Rails in one go. It takes less than 15 minutes to setup once downloaded (depending on system speed) and less than 10 minutes to update in the future (depending on the amount of sites you have). Start by following the instructions at http://www.rubyenterpriseedition.com/download.html (download, extract, install). Keep the settings as the default ones REE assigns.

Now add the following to the .bash_profile, and .bashrc files of any users that'll affect the installation (root, kete, and yourself for example). Be sure to use the correct path for REE; it varies by release. Replace the X's in the string below.

# Use correct Ruby, RubyGem paths
PATH=/opt/ruby-enterprise-1.8.6-2008XXXX/bin:$PATH
export PATH

Then as both root and the kete user, check that we are using the correct RubyGems version:

$ which gem
/opt/ruby-enterprise-1.8.6-2008XXXX/bin/gem # should look something like this with correct date

Additional Setup Instructions

MySQL

Now we initialize and configure mysql to start at boot time. We'll also set the mysql root password and set up unicode to be the default charset. Make sure you save your mysql root password, you'll need it later!

$ sudo -u mysql mysql_install_db5
$ sudo launchctl load -w /Library/LaunchDaemons/org.macports.mysql5.plist
$ mysqladmin -u root password 'new-password'

You'll also want to append this to your PATH in ~/.profile file:

/opt/local/lib/mysql5/bin

We want Unicode (utf8) to be our mysql default character set, too. Create /opt/local/etc/mysql5/my.cnf via sudo and your favorite text editor and place this in it:

[mysqld]
# making utf8 the default
init-connect = SET NAMES utf8
character-set-server=utf8
collation-server=utf8_general_ci

Restart mysql, connect to the default database, and check that it now has the right settings:

$ sudo launchctl stop org.macports.mysql5
$ sudo launchctl start org.macports.mysql5

If the above doesn't work (it should after next reboot), use this:

$ sudo /opt/local/etc/LaunchDaemons/org.macports.mysql5/mysql5.wrapper stop mysql5
$ sudo /opt/local/etc/LaunchDaemons/org.macports.mysql5/mysql5.wrapper start mysql5

You can confirm that required (system, server) charset variables now point at utf8 by connecting to the mysql database as mysql root (remember you set that password above) and running "show variables;"

YAZ and Zebra

Kete relies on specific versions of YAZ and Zebra, so the older versions must be compiled from source.

root@host: # sudo mkdir /usr/local/src
root@host: # sudo chmod 777 /usr/local/src
root@host: # cd /usr/local/src

We have to install a prerequisite for YAZ before we can proceed. Because of having pkg-config installed by our earlier ports under /opt/local/bin, yaz configure ends up pointing at some libs under /opt/local rather than /usr/local, and fails. To work around this, we install pkg-config under /usr/local and point YAZ at it:

root@host: # curl -L http://pkgconfig.freedesktop.org/releases/pkg-config-0.22.tar.gz -O
root@host: # tar xfz pkg-config-0.22.tar.gz
root@host: # cd pkg-config-0.22
root@host: # ./configure
root@host: # make
root@host: # make install

then we alter our environment so YAZ builds correctly:

PATH=/usr/local/bin/:$PATH
export $PATH

Now we can build YAZ correctly:

root@host: # sudo mkdir /usr/local/src
root@host: # sudo chmod 777 /usr/local/src
root@host: # cd /usr/local/src
root@host: # wget http://ftp.indexdata.dk/pub/yaz/yaz-2.1.54.tar.gz
root@host: # tar xfz yaz-2.1.54.tar.gz
root@host: # wget http://ftp.indexdata.dk/pub/zebra/idzebra-2.0.6.tar.gz
root@host: # tar xfz idzebra-2.0.6.tar.gz
root@host: # cd yaz-2.1.54
root@host: # ./configure --prefix=/usr
root@host: # make
root@host: # sudo make install
root@host: # cd ../idzebra-2.0.6
root@host: # ./configure --prefix=/usr --with-yaz=../yaz-2.1.54 --enable-mod-alvis
root@host: # make
root@host: # sudo make install

ImageMagick

Kete uses ImageMagick and Rmagick (the ruby binding for Imagemagick) to create thumbnails of images, make captcha images, etc. I'm not super happy with Rmagick's performance, so we might move to ImageScience in the future, but for you now, we need to install this stuff for images.

Unfortunately installation of Rmagick on Mac OS X isn't as easy it should be because the MacPorts version of ImageMagick isn't configured correctly to find the ghostscript fonts. This is a well known issue and thankfully there are instructions for how to make it work.

To install ImageMagick and Rmagick correctly for 10.4 follow steps 4 through 6 in this guide:

http://rmagick.rubyforge.org/install-osx.html

Or on 10.5 use this installer: http://rubyjudo.com/2007/11/3/rmagick-for-rails-on-os-x-leopard

Memcached

We'll turn it on as a daemon that will run at boot. You may want to start it only when you are doing development, since it can eat up RAM. You may just want to manage it directly from the command line via the "memcached" command itself.

$ sudo curl -L http://waltermcginnis.com/local.server.memcached -o /Library/LaunchDaemons/local.server.memcached
$ sudo launchctl load -w /Library/LaunchDaemons/local.server.memcached
$ sudo launchctl start local.server.memcached

If you aren't running your development Kete server, you probably want to turn off the Memcached daemon with the following (just remember to turn it on again when you do!):

$ sudo launchctl stop local.server.memcached

HTTP Request Server

For the following section, you have two choices to serve HTTP requests. Nginx ("engine X") or Apache2. Each has their own advantages, so the choice is yours, depending on what you have available to work with.

Note: Neither of these are nessesary when running in development or test mode. You can despense with the http request server when requests are made from the same computer as the application is being run on. When you deploy to production, then you'll want one of these setup.

Nginx

Pros: Nginx allows you to configure how many mongrel servers you want to have and at which IPs. A good choice if you plan to deploy your application around the globe.
Cons: Not Nginx related, but using Nginx requires having multiple mongrels on a single computer, and it can use a lot of memory and can be a pain to manage at deploy time.

Grab the latest tarball from http://sysoev.ru/nginx/download.html and do the following (adjust version numbers accordingly).

root@host: # cd /usr/local/src
root@host: # wget http://sysoev.ru/nginx/nginx-0.6.32.tar.gz
root@host: # tar xfz nginx-0.6.32.tar.gz
root@host: # cd nginx-0.6.32/
root@host: # ./configure --prefix=/usr/local/nginx --sbin-path=/usr/local/sbin --with-http_ssl_module
root@host: # make
root@host: # sudo make install

You'll probably want to get nginx to start up automatically at boot as well.

Important Note: At this point, Nginx is installed but not yet configured for our Kete site. We'll handle that in a separate step once we have Kete installed. Until then, web requests will throw an error until you have actually deployed your Kete application and started a mongrel cluster to match your settings in /usr/local/nginx/conf/nginx.conf

You may want to add /usr/local/sbin to your PATH.

root@host: # exit
$ PATH=/usr/local/sbin/:$PATH
$ export $PATH

Apache2

Pros: Quick to setup, easy to deploy and restart applications. Minimal memory consumption. Simple site configuration.
Cons: Can't deploy across mulitple Apache2 configurations.

Enabled "Web Sharing" under System Preferences > Sharing. This will turn on Apache.

Then install the passenger gem and install the module.

root@host: # gem install passenger
root@host: # passenger-install-apache2-module

Copy the Apache2 config lines it gives you at the end of the file to the end of your httpd.conf configuration file at /etc/apache2/httpd.conf. The lines look similar to this (paths will be different if using REE):

LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-2.0.3/ext/apache2/mod_passenger.so
PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-2.0.3
PassengerRuby /usr/bin/ruby

Open up /etc/apache2/httpd.conf in your favourite editor, and change the following settings:

User    <-   the user running the kete app(s). Usually kete or yourself.
Group   <-   the group of the user running the kete app(s)

In the same file, uncomment the following line:

Include /private/etc/apache2/extra/httpd-vhosts.conf

In /etc/apache2/extra/httpd-vhosts.conf, uncomment the following line:

NameVirtualHost *:80

Run the following commands (otherwise Kete isn't installable because of missing dependancies).

root@host: # ln -s /usr/local/bin/zebrasrv /usr/bin
root@host: # ln -s /usr/local/bin/zebraidx /usr/bin

And finally, to make the apache restart command more consistant for the rest of the guide, type

root@host: # mkdir /etc/init.d
root@host: # ln -s /usr/sbin/apachectl /etc/init.d/apache2

With those changes made (and files saved), restart Apache:

root@host: # /etc/init.d/apache2 restart

and then look for any errors causes by bad configuration by running:

root@host: # tail -n 200 /var/log/apache2/error_log

Important Note: At this point, Apache2 and Passenger are installed but not yet configured for our Kete site. We'll handle that in a separate step once we have Kete installed. Until then, web requests will throw an error until you have actually deployed your Kete application.

Next step:
Setting Up the Environment