Dead Ink Vinyl

I got CouchDB up and running as a service on my MBP OSX Leopard this past Monday. It wasn’t as straight-forward as I’d hoped, so I thought I’d share my process for the benefit of others.

Installing CouchDB

I installed CouchDB from source. This requires the Leopard development tools (Xcode) and MacPorts. I expect all developers to have Xcode installed and most developers to have MacPorts installed, so I won’t detail those steps here.

First, install CouchDB’s dependencies using MacPorts:

sudo port install icu erlang spidermonkey

Download CouchDB and extract it. This is standard configure, make, make install territory here:

./configure
make && sudo make install

Wasn’t that easy?

Creating a couchdb System Account

Find a user number that is available. To see a list of what numbers are already in use, run:

dscl . -list /Users UniqueID | awk '{print $2}' | sort -n

Now find a group number that is available. To see a list of what numbers are already in use, run:

dscl . -list /Groups PrimaryGroupID | awk '{print $2}' | sort -n

On my system, number 103 was available for both a user number and a group number. The rest of this article assumes you are using 103 as well.

The following commands create the group and the user and set the user’s home directory to the CouchDB lib folder.

sudo dseditgroup -o create -i 103 -r "CouchDB Users" couchdb
sudu dscl . -create /Users/couchdb
sudu dscl . -create /Users/couchdb UniqueID 103
sudu dscl . -create /Users/couchdb UserShell /bin/bash
sudu dscl . -create /Users/couchdb RealName "CouchDB Administrator"
sudu dscl . -create /Users/couchdb NFSHomeDirectory \
        /usr/local/var/lib/couchdb
sudu dscl . -create /Users/couchdb PrimaryGroupID 103
sudu dscl . -create /Users/couchdb Password *

Finally, we give the couchdb user ownership of the CouchDB lib and log directories:

sudo chown -R couchdb:couchdb /usr/local/var/<strong>lib</strong>/couchdb
sudo chown -R couchdb:couchdb /usr/local/var/<strong>log</strong>/couchdb

DONE! Now you can launch CouchDB as the couchdb user instead of root.

sudo -u couchdb couchdb

Running as a Service

To control CouchDB using launchctl, I needed to add the appropriate PATH information to CouchDB’s Launch Daemon plist so that gawk is found. Unfortunately, I couldn’t find a solution to edit the plist in-place as a privileged user, so I copied the file to the /var/tmp directory without root privileges so that I could update the copy.

Creating a copy of the plist and opening it for editing is done by:

cp /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist \
        /var/tmp/org.apache.couchdb.plist
open /var/tmp/org.apache.couchdb.plist

In the Property List Editor that opens, follow this steps:

1. Open Root → EnvironmentVariables
2. Click on Add Child
3. Name: PATH
4. Value: /bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/local/bin:/opt/local/sbin
5. File → Save
6. Quit Property List Editor

Then copy the updated plist over the original plist:

sudo cp /var/tmp/org.apache.couchdb.plist \
        /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist 

Now CouchDB can be controlled and monitored by the standard Leopard daemon manager:

sudo launchctl load \
        /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist 

Launch CouchDB on Startup

To automatically launch on start up, run

sudo ln -s /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist \
        /Library/LaunchDaemons/org.apache.couchdb.plist

Congratulations! You have CouchDB running as a system service that will start when you boot your Mac. Let the fun commence.

I’d Like to Thank the Academy…

I’d like to thank the following sites and resources for providing me enough information to piece together the process:

• CouchDB Source Code: README
• SysAdmin’s Chronicles: Creating a System Account in Mac OS X 10.5 Leopard
• evang.eli.st: Installing Postgres 8.2 on Leopard

I particularly recommend the evang.eli.st article, as it explains the dscl command, which may be an unfamiliar account management tool.

I should point out that evang.eli.st also has a complete write-up on how to install CouchDB on OSX. That walk-through is almost a year old, though, and entails editing the Makefile—which doesn’t sit well with me. However, where Leopard departs from standard UNIX behavior, I cease being an aficionado, so his tweaks may be important in ways I haven’t yet discovered.

I don’t know if it’s father-to-be hormones or just that the story is so poignant, but I can’t read Daniel H. Steinberg’s On why I use a Mac without tearing up.

Why do I use a Mac? I can’t imagine that I would have these memories of the last two months of Elena’s life if we used anything else. That may not convince you either. But tomorrow is the second anniversary of my little girl’s death and I will have movies to watch and pictures to look at.

I can’t think of a better reason. Amy and I share our condolences and wish your family the best.

Three and a half years ago I wrote an unflattering article responding to Alan Cooper’s book The Inmates Are Running the Asylum. Recently, I had an instructor in one of my HCI courses recommend Cooper’s books and I wondered if I should give them another chance. I started reading Inmates again and found it to be every bit as inane today as I found it in 2004. I quietly put Alan’s books aside again and continued reading other software interface design books.

In October, I started on Jeff Johnson’s GUI Bloopers 2.0. Due to the “cookbook”-esque layout of the content, I had been delightfully jumping around the book as time and interest permitted. Today I decided to read the book properly from the beginning. That led to me read pages 28-29 about how imposing arbitrary restrictions is a Bad Thing™. Johnson provides these examples of arbitrary restrictions that some software imposes on its users:

• limiting person names to 16 characters
• allowing table rows to be sorted by at most 3 columns
• providing Undo for only the last three actions
• requiring a fax number in all address book entries even though some users don’t have fax machines

Okay. I understand why limitations like those exist in software applications, but I also understand how they can seem arbitrary and counterproductive to users. Reading on, I got to page 34 where Johnson references Alan Cooper.

He [Alan Cooper] points out that programmers are trained to handle all cases that can arise in a software system and so often spend inordinate amounts of time and effort designing GUIs that cover low probability cases as well as higher probability ones.

Low probability cases like… persons with more than 16 characters in their names? sorting tables by more than three columns? This is the crux of the problem: An unsupported “low probability case” for one user is an “arbitrary restriction” to another user.

It’s unfair to complain about programmers spending time on “low probability cases” and then complain that your low probabality case wasn’t implemented. (Sorting on more than three columns? Seriously? If you have those kinds of needs, maybe you shouldn’t be using an Excel sheet as a database. Just a thought.)