old.kete.net.nz :Documentation

Topic: Creating a Kete Development Environment on Mac OS X

Topic type:

• Topic

Outlines the steps necessary to get Kete running on Mac OS X, along with best practices for using Mac OS X as a development environment.

This is now superseded by the Installation Guide

Keeping around for historical reference

Background

Note: Pay careful attention to each step of this guide. Quite often the current step is dependent on the last step's context, such as current directory. Also this document assumes that your account has access to sudo (i.e. is an adminstrative account).

I'll be using MacPorts (the package manager formerly known as DarwinPorts) for it's speed and convenience. This will result in in all our code living under /opt. There are few existing guides that cover the basics of installing the Ruby on Rails stack on Mac OS X with MacPorts. If you choose to go with PostgreSQL than Robby on Rails' guide will do the trick. For MySQL 5, http://rid.onkulo.us/archives/18-installing-ruby-on-rails-on-mac-os-x is what you are after.

The official Rails wiki install guide for Mac OS X Tiger using MacPorts can be found here. It's a bit convoluted, but maybe useful as a reference.

Install MacPorts

For completeness sake, I'll cover the steps to get the Ruby on Rails stack (mysql) in place via MacPorts anyway:

First, install MacPorts if you haven't already (just do "sudo port selfupdate" if you have), the latest being version 1.5 as of this writing, via the instructions found at http://trac.macosforge.org/projects/macports/wiki/InstallingMacPorts.

Important Note: Install Apple's X11 (if you haven't already, it should be found at Applications > Utilities > X11) as your FIRST STEP in the MacPorts install. It will make things go much smoother when you get to ImageMagick based stuff.

Also make note that you need to update ~/.bash_profile to have your PATH have /opt/local as the first directory.

Install Ruby on Rails Stack via MacPorts

Next, we install the various ports we'll need for Ruby on Rails and Rails development:

Ruby and Ruby Gems are first. You'll also want Subversion to grab Kete and manage your project's source code, so I'll throw that in here, too. We'll get MySQL5 and the ruby adaptor for it. Kete relies on Memcached, ImageMagick, and RMagick (gem is problematic, use port), too. They may take quite awhile depending on your machine:

$ sudo port install ruby rb-rubygems subversion mysql5 +server rb-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.

$ 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:

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;"

I install Rails via Ruby Gems since it's the most up to date:

For consistency between our Kete production and development environments we'll install both mongrel (app server) and nginx (proxy server). Install mongrel via gems:

Choose the appropriate version of the gems for your Mac, usually the latest "ruby" version. I.e. not "mswin32".

So at this point, you should have installed MacPorts and a functional bare bones Ruby on Rails stack ready for development (excluding nginx for now), but haven't set up anything for a specific Rails app, yet.

Install Kete's Dependencies Software

Now to get into Kete's dependencies. First up is YAZ, http://indexdata.dk/yaz/, which we'll need for the Ruby-Zoom gem which we'll grab with all the other required gems for Kete.

Unfortunately, at the time of this writing, version 3x of YAZ doesn't seem to fully work with ZOOM Extended Services. This may be a misconfiguration on my part or there may be a problem with 3x, but version 2.1.56 works as expected. We'll install that version.

If you have installed a 3x version in the past, do this first:

$ cd /opt/local/src
$ cd yaz-3.0.8
$ sudo make uninstall
$ cd ../idzebra-2.0.14 # or whatever version of zebra you were using
$ sudo make uninstall
$ sudo gem uninstall zoom # if you have previously installed zoom again yaz 3x, then after building yaz 2.1.54, repeat the steps for zoom 0.4.0 gem below

If you haven't in the past, create a /opt/local/src directory, untar the file there, and prepare to build it, like so:

$ sudo mkdir /opt/local/src
$ sudo chmod 777 /opt/local/src
$ cd /opt/local/src
$ curl -L http://ftp.indexdata.dk/pub/yaz/yaz-2.1.56.tar.gz -O
$ tar xfz yaz-2.1.56.tar.gz
$ cd yaz-2.1.56

YAZ has a standard *nix installation process. However, I'm going to install under /opt/local rather /usr/local. Note that "--enable-shared" as required by Ruby-Zoom is the default, so we don't specify it.

$ ./configure --prefix=/opt/local
$ make
$ sudo make install

Kete uses the Zebra search engine for all it's searches and a number of other things. Let's install it now (held back to 2.0.6 that we know works, this is also why we require the --with-yaz option):

$ cd /opt/local/src
$ curl -L http://ftp.indexdata.dk/pub/zebra/idzebra-2.0.6.tar.gz -O
$ tar xfz idzebra-2.0.6.tar.gz
$ cd idzebra-2.0.6
$ ./configure --prefix=/opt/local --with-yaz=../yaz-2.1.56
$ make
$ sudo make install

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 follow steps 4 through 6 in this guide:

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

Finally, it's the Memcached daemon's turn. We'll install it, then 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 port install memcached # this may take a few tries, use a "sudo port selfupdate" and try again if you have problems
$ 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

Setup a Development Kete (for demo)

Time to download the actual Kete application via a subversion checkout. There are some convenience scripts, "rake tasks" in the Ruby/Rails world, that we'll use to handle most of the other installation of the other required pieces. So let's do it:

I use ~/apps for developing my rails apps usually, so we'll create that first. You'll also want to choose a name for your app at this point, usually something that matches the eventual production domain name is good. Kete is a fairly extensive app, the checkout can take a bit.

$ mkdir ~/apps
$ cd ~/apps
$ svn checkout http://svn.kete.net.nz/projects/kete/trunk your_app_name
$ cd your_app_name

Now we need to set up mysql for use with our new app. This is pretty simple, but does require some simple editing of a file and running some mysql stuff. We'll assume you are still in your_app_name directory. Here goes:

Open config/database.yml in your text editor. My tendency is to have my username and password settings match what I'm going to put on my production server (I use svn via ssh rather than the clear text http for my app checkout). So I would edit those. You'll also want to change occurances of "kete_" to "your_app_name_", for example "kete_development" becomes "your_app_name_development".

After saving config/database.yml, you want to open a mysql session and create your databases and grant rights on them to whatever you chose for username in the file:

$ mysql -u root -p mysql # enter the mysql root password you set above
...
mysql> create database your_app_name_production;
mysql> grant all on your_app_name_production.* to 'the_username_you_chose'@'localhost' identified by 'the_password_you_chose';
mysql> create database your_app_name_development;
mysql> grant all on your_app_name_development.* to 'the_username_you_chose'@'localhost';
mysql> create database your_app_name_test;
mysql> grant all on your_app_name_test.* to 'the_username_you_chose'@'localhost';
mysql> quit;

We have some more set up to do before the first time we run Kete. I've wrapped most of the Kete specific gem installs up in a single command. Next is priming the database and then it will be on to configuring Mongrel so that you can have a first look at your new Kete!

$ rake prep_app
...
$ rake db:bootstrap
$ script/server # this will start mongrel on port 3000

Now go to http://127.0.0.1:3000/ in a browser and you should be prompted to login with the default administrator account which "admin" with a password of "test". If you just want to take a look at what Kete can do, this might be sufficient for your needs and you stop here. Follow the directions to configure Kete and when you reach the point where it asks you to restart the server, simply go back to where you started "script/server" and hit "control-c" twice. Type "script/server" to bring the server back up.

If, however, you are doing further development or deployment of Kete, you'll probably want to do something like the following:

• import Kete's source code into your own project's subversion repository, so you can customise it
• prepare for a deployment to a production server
• set up nginx on your Mac to run as a proxy web server for multiple projects in development

If you want to continue, go ahead and quit Mongrel with two "control-c"s.

If you want to continue with your development Kete, see the "Configuration" section. To restart server at the end, go back to the shell where Mongrel is running and do two "control-c"s in a row. Then rerun the "script/server" command.

Importing Kete into your Subversion Repository (Best Practice)

As outlined here and here, you can use the piston gem to do easy subversion vendor branch management for an entire Rails application based on an open source Rails application like Kete, rather than just plugins.

This means it is easy to track Kete upgrades while allowing your own customisations.

We'll assume that you have created a subversion repository that is accessable via svn+ssh on another host. Note that you shouldn't have created the trunk directory under your project yet.

We'll have to back up slightly. If you have read all the way through, you can skip to this step rather the original "svn checkout" of Kete.

$ cd ~/apps
$ mv your_app_name your_app_name_bak # assuming you have this around from before
$ svn co svn+ssh://some_host/path/to/svn_repository/your_app_name
$ cd your_app_name
$ piston import http://svn.kete.net.nz/projects/kete/trunk/ trunk/
$ cp your_app_name_bak/config/database.yml trunk/config/ # copy our previously configured database settings
$ svn add trunk/config/database.yml
$ svn commit -m "Imported Kete as the basis of my project"

Personally, I like to work out of "your_app_name" rather than "your_app_name/trunk", so I also do the following.

$ cd ~/apps
$ mv your_app_name your_app_name_bak2 # will rm -rf after i'm satisfied that everything is fine
$ svn co svn+ssh://some_host/path/to/svn_repository/your_app_name/trunk your_app_name
$ cd your_app_name # rm -rf your_app_name_bak* at your leisure

Deployment using Capistrano (Best Practice)

In order to proceed with deployment, I'll assume that you have prepared a single host (for web, app, and db roles) for production as outlined in the "Preparing a Debian Etch Host to be Deployed to for Kete" guide. If you haven't, do that first. We'll use the Capistrano lingo and call that our "target" from here on out. You might also want to check out capify.org for reference, specifically Getting Started: Rails. There is also a wiki that may be useful as a reference.

One key thing to remember, it's the point of Capistrano really, is that you are running all the commands in your_app_name directory on your development machine, unless otherwise noted.

But enough reading, let's get to it. First up, capify your app. This usually means running one command, then editing the resulting deploy.rb file to point at your svn repository, production host, etc. However, Kete includes a partially preconfigured Capistrano 2.0.0 Capfile and config/deploy.rb to simplify the process. You will still need to edit config/debloy.rb with a text editor and change the following settings to make sense for you:

:application # i.e. your_app_name, corresponds to directory name you are deploying from
:repository # this is your project subversion repository, i.e. svn+ssh://host/path_to_repository/your_app_name/trunk
role :app # your host address, ip or domain
role :web # same if you are deploying to only one host as i assume you are
role :db # same if you are deploying to only one host as i assume you are
:mongrel_servers # this is how many mongrel instances in your mongrel
cluster, see note below about nginx and mongrel

Note on mongrel and nginx: Choose a number for :mongrel_servers that makes sense for the resources on deployment target. This depends largely on the RAM and CPU resouces on the host. It may take some experimentation to find the "sweet spot". I usually figure about 128Mb of RAM per mongrel instance (Rmagick which Kete currently depends on is a RAM hog). There is a lot of discussion about this you can find via google. You will need to edit /usr/local/nginx/conf/nginx.conf on your target by hand to match your Mongrel ports that you set up, then restart nginx with "sudo /etc/init.d/nginx restart". If you change your Mongrel settings in the future, you'll need to edit/restart nginx again.

Also note that for svn+ssh you will probably want to set up ssh key in the repository host's user account. So you'll need to do a keygen on your target and copy that to your repository user's .ssh/authorized_keys for your target host and user.

Because our target hasn't been deployed to before, we have a few extra steps than normal to get our environment ont that machine setup, but these are all wrapped up in one command (although it may take quite awhile):

You'll probably want to "svn commit" your config/deploy.rb, then do this:

cap deploy:first_time

From now on (there are exceptions, for example if you have to install new gems or editing your mongrel settings), you just do the following to update your live server (from your_app_name directory on your development machine):

cap deploy

You are now ready to visit your new site! Proceed to "Configuration".

Configuration

Open the site up in your browser and will be prompted for the default administrator account login and password. These are "admin" and "test". Then follow the directions on the site for configuring your new Kete.

Important: You should change the default administrator password right away.

When you are done, you'll be asked to restart your server. If you have used Capistrano to deploy, all you need to do is the following:

cap deploy:restart

If you are just on a development host, then it depends on what your set up is. See notes about Nginx and Mongrel.

Set Up Nginx for Multiple Project Development (Optional)

The Kete Project chose Nginx (http://nginx.net/) as the proxy in front of whatever Mongrels app servers it's running. Nginx is fast and reliable and there is a lot of energy behind it in the Rails community.

Grab the latest stable version from the download link found on http://wiki.codemongers.com/NginxGettingStarted. Untar it from whereever you downloaded it to into /opt/local/src. Again, fairly standard *nix installation. Our only difference is that we'll use /opt/local rather /usr/local and that we need to grab the PCRE library, too.

$ sudo port install pcre
$ cd /opt/local/src
$ curl -L http://sysoev.ru/nginx/nginx-0.5.30.tar.gz -O
$ tar xfz nginx-0.5.30.tar.gz
$ cd nginx-0.5.30
$ ./configure --prefix=/opt/local/nginx
$ make
$ sudo make install

Although when in development on our local machine we will probably only be running one mongrel instance at a time and we may start and stop that directly from the command line, I find it a nice convenience to able to support different hostnames for different projects listening on port 80 like normal web requests rather than localhost and a port number. Here are the steps:

• Configure our new project's mongrel to start on it's own specific port.
• Add a dummy hostname entry in /etc/hosts for our project.
• Configure Nginx to send requests for that dummy hostname to the correct mongrel cluster.

Mongrel: from app directory of your project.

mongrel_rails cluster::configure -p 8000 -N 1

So for the next app, you would change a different port than 8000. The -N option specifies how many mongrels to run in your cluster. We are in development, so we only choose 1. If we chose 3, ports 8000, 8001, and 8002 would be used by this app. Mongrel will now be running in the background and you will need to use the following to start and stop your mongrel cluster from within your app's directory:

mongrel_rails cluster::start
mongrel_rails cluster::stop

Dummy Hostname: add to /etc/hosts

With root privileges edit /etc/hosts and add a new hostname to point at your app, just after the first "localhost" entry:

127.0.0.1       your_app

For additional apps, just add another line with a different hostname.

Proxy Your Dummy Hostname: add to /opt/local/nginx/conf/nginx.conf

$ sudo cp /opt/local/nginx/conf/nginx.conf /opt/local/nginx/conf/nginx.conf.orig

Then edit with root privileges /opt/local/nginx/conf/nginx.conf to ADD (not replace) something like the following adjusting your_app, your_user, and upstream lines to match your mongrel cluster ports appropriately from the following file:

You'll also want to uncomment the "log_format" lines, too. It won't start up properly otherwise. If your paths to things vary, you'll have to adjust them.

For additional projects, do the same thing, but adjust servername and ports to suit. Note that this doesn't support ssl/https. When you are satisfied, start nginx with this:

sudo /opt/local/nginx/sbin/nginx -c /opt/local/nginx/conf/nginx.conf

To stop nginx, do this:

ps auxw | grep nginx # choose the pid for the master process run by root from the result
sudo kill the_master_pid

I haven't found a launchd plist for nginx for starting up automatically at boot yet.

Additional Development Niceties

If you are emacs person like me, you'll probably also want to check out the installation and configuration of Aquamacs to suit Ruby and Ruby on Rails development at http://blog.katipo.co.nz/?p=38. It depends on some of the things outlined in this article being in place, so you'll want to hold off on that until after completing these steps. Some stuff is useful to emacs users in general.

Walter McGinnis

was the last to edit Creating a Kete Development Environment on Mac OS X

on Aug 4th, 2008 at 5:04 PM

Walter McGinnis

created Creating a Kete Development Environment on Mac OS X

on Aug 29th, 2007 at 11:39 PM

• Flag as:
• • inaccurate
  • duplicate
  • inappropriate
  • entered by mistake
  • has typos