Topic: Mac OS X Installing Required Software

Topic type:

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 Mac OS X 10.6.6 (Snow Leopard) and Mac OS 10.7.x (Lion). Mac OS X 10.4 (Tiger) and Mac OS 10.5.1 (Leopard) are covered in earlier versions of this topic. Please refer to 'History' of this topic to view earlier versions if you want to install based on those versions of Mac OS X. Note, Leopard (10.5) will probably work fine with this version of instructions, but hasn't been tested.

Install Homebrew (MacPorts installation depreciated)

Follow the instructions at to install Homebrew software package manager system on your system. Homebrew requires that XCode is installed.

A note about Homebrew and root/sudo

Homebrew is designed to work as much as possible without sudo. You use your own user account or the Kete user account you set up to install software. Pay attention throughout the guide for notes telling you when you should skip "sudo" or using the root account.

More information on why Homebrew doesn't use root permissions and sudo can be found in Homebrew's installation guide and project pages.

Install Required Software for Running Kete

So lets get installing. Run the followig from the command line (i.e. or another shell):

$ brew install git zebra mysql memcached imagemagick

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

$ brew install poppler wv lynx

(optional - enables support for harvesting embedded metadata in uploaded files, see mini_exiftool gem step later)

$ brew install libexif exiftool

Installing the Rails framework

For the moment at least, Kete standardizes on the Ruby Enterprise Edition version of Ruby 1.8.7. It is a product from the same people that make mod_rails/Passenger (discussed at the bottom of this page). It's optimized to run faster than a standard installation of Ruby. It requires a few extra installation steps, but it's well worth the effort. (for instructions on using debians packages, see an older version of this topic)

$ brew install ruby-enterprise-edition

Additional Setup Instructions

Some of these do actually require 'sudo'. Use as noted.


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!

$ unset TMPDIR
$ mysql_install_db --verbose --user=`whoami` --basedir="$(brew --prefix mysql)" --datadir=/usr/local/var/mysql --tmpdir=/tmp # note commands for root password change
$ mkdir -p ~/Library/LaunchAgents
$ cp /usr/local/Cellar/mysql/5.x.xx/com.mysql.mysqld.plist ~/Library/LaunchAgents/ # replace x.x.xx with version found under that directory
$ launchctl load -w ~/Library/LaunchAgents/com.mysql.mysqld.plist $ mysqladmin -u root password 'new-password'
$ # run second command to change host specific root password as noted after mysql_install_db command


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.

$ cp /usr/local/Cellar/memcached/x.x.x/com.danga.memcached.plist ~/Library/LaunchAgents/ # replace x.x.x with actual version number directory

Now it is ready to run:

$ launchctl load -w ~/Library/LaunchAgents/com.danga.memcached.plist

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!):

$ launchctl stop local.danga.memcached

HTTP Request Server

We recommend Apache 2 in combination with Ruby Enterprise Edition for optimal performance.If you'd prefer to use Nginx with Mongrel, see an older version of this topic.

Apache 2 comes preinstalled on Mac OS X and Passenger comes with Ruby Enterprise Edition, which we installed earlier so, go ahead and install the passenger module for Apache.

$ sudo su -
root@host: # passenger-install-apache2-module

Copy (using a text editor as root user) the Apache2 config lines it gives you at the end of the file to the end of your apache2.conf configuration file at /etc/apache2/apache2.conf. The lines look similar to this (paths may differ depending on which ruby implementation you're using):

LoadModule passenger_module /usr/local/Cellar/ruby-enterprise-edition/1.8.7-20XXXXXX/lib/ruby/gems/1.8/gems/passenger-x.x.x/ext/apache2/

Some of Kete's downloading functionality requires an authorization step.  If used a lot this potentially can slow all requests being served from the site.  Thankfully there is an easy solution that Kete knows to use if enabled; X-sendfile.  First, visit and get the latest .tar.gz source code. You need to do the following to set it up:

root@host: # cd /usr/local/src/; cp ~/Downloads/the_file ./ # substitute downloaded filename
root@host: # tar xfz mod_xsendfile-0.xx.tar.gz
root@host: # cd mod_xsendfile-0.xx
root@host: # apxs -cia mod_xsendfile.c

Then you need to add the following to your Apache2 config file (either global, or in a virtualhost):

XSendFile on

And force a reload of apache:

root@host: # apachectl force-reload

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

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

Discuss This Topic

There are 10 comments in this discussion.

Read and join this discussion

join this discussion

Creative Commons Attribution-Share Alike 3.0 New Zealand License
Mac OS X Installing Required Software by Walter McGinnis is licensed under a Creative Commons Attribution-Share Alike 3.0 New Zealand License