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.