Logo Devoh

Installing CouchDB on Mac OS X 10.5 Leopard

Trial and Error

CouchDB is a RESTful, document-based database that uses map-reduce with JavaScript as its query language. Its innovative use of some lesser known projects make its existence possible, but they also tend to complicate its installation process. The large majority of the Mac OS X installation instructions available for CouchDB utilize MacPorts for its dependencies, leaving those of us who prefer to install from source in the dark.

I felt that is was worth pursuing a from-scratch installation, but alas I ended up spending many more hours than any sane person would to accomplish such a trite goal. It ended up being a trial and error process to figure out each missing piece until the puzzle was complete. It is my hope that there are others like myself who will benefit from this information, but, if not, I write it is as a personal reference.

This guide provides step-by-step instructions on installing the requisite dependencies, and, ultimately, CouchDB itself. It should provide a fairly complete description of each task along the way, but let me know if you run into snags or have suggestions on improving the content.

Install Erlang

CouchDB is written in Erlang, so we'll need to install it before we'll be able to run CouchDB.

curl -O http://www.erlang.org/download/otp_src_R12B-5.tar.gz
tar xzvf otp_src_R12B-5.tar.gz
cd otp_src_R12B-5
./configure --enable-hipe --enable-smp-support --enable-threads
make
sudo make install

International Components for Unicode

CouchDB's internationalization support is provided by the ICU library.

curl -O http://download.icu-project.org/files/icu4c/4.0.1/icu4c-4_0_1-src.tgz
tar xzvf icu4c-4_0_1-src.tgz
cd icu/source
./runConfigureICU MacOSX --prefix=/usr/local
make
sudo make install

SpiderMonkey

CouchDB relies on the same SpiderMonkey JavaScript engine that Firefox uses. Unfortunately, the build process for this project seems surprisingly neglected considering its prevalence within Mozilla's products.

You'll first need to install the Netscape Portable Runtime, as SpiderMonkey relies on this library for its thread support.

curl -O http://ftp.mozilla.org/pub/mozilla.org/nspr/releases/v4.7/src/nspr-4.7.tar.gz
tar xzvf nspr-4.7.tar.gz
cd nspr-4.7/mozilla/nsprpub
./configure
make
sudo make install

Now SpiderMonkey itself can be installed, but we'll have to apply some patches from the MacPorts port to get it to build properly.

Download and extract the source, first.

curl -O http://ftp.mozilla.org/pub/mozilla.org/js/js-1.7.0.tar.gz
tar xzvf js-1.7.0.tar.gz
cd js/src

Next, fetch and apply the patches.

curl http://trac.macports.org/export/44341/trunk/dports/lang/spidermonkey/files/spidermonkey-1.5-build.patch | patch -p0
curl http://trac.macports.org/export/44341/trunk/dports/lang/spidermonkey/files/spidermonkey-1.5-threadsafe.diff | patch -p0
curl http://trac.macports.org/export/44341/trunk/dports/lang/spidermonkey/files/spidermonkey-1.5-header.diff | patch -p0
curl http://trac.macports.org/export/44341/trunk/dports/lang/spidermonkey/files/patch-config-Darwin.mk | patch -p0

Then, replace the placeholders in the Makefile.

sed -i -e 's|__PREFIX__|/usr/local|' Makefile.ref
sed -i -e 's|__USER__|root|' Makefile.ref
sed -i -e 's|__GROUP__|wheel|' Makefile.ref

And, finally, build and install.

make -f Makefile.ref LIBDIR="/lib" SO_SUFFIX=dylib JS_THREADSAFE=1
sudo make -f Makefile.ref install
sudo ranlib /usr/local/lib/libjs.a

CouchDB

We now have all of the dependencies in place, and we're ready to proceed with the installation of CouchDB itself.

curl -O http://www.smudge-it.co.uk/pub/apache/incubator/couchdb/0.8.1-incubating/apache-couchdb-0.8.1-incubating.tar.gz
tar xzvf apache-couchdb-0.8.1-incubating.tar.gz
cd apache-couchdb-0.8.1-incubating
./configure --prefix=/usr/local
make
sudo make install

User and Group

We need to create a user and group now, but I won't go into too much detail here as it has already been covered here before in the PostgreSQL guide.

For the purposes of this tutorial, let's assume an ID of 115 for both the user and the group.

First, create the _couchdb user.

sudo dscl . create /Users/_couchdb UniqueID 115
sudo dscl . create /Users/_couchdb PrimaryGroupID 115
sudo dscl . create /Users/_couchdb RealName "CouchDB Server"
sudo dscl . create /Users/_couchdb NFSHomeDirectory /usr/local/pgsql/
sudo dscl . create /Users/_couchdb Password "*"
sudo dscl . append /Users/_couchdb RecordName couchdb

Then, create the _couchdb group.

sudo dscl . create /Groups/_couchdb
sudo dscl . create /Groups/_couchdb PrimaryGroupID 115
sudo dscl . create /Groups/_couchdb RealName "CouchDB Users"
sudo dscl . append /Groups/_couchdb RecordName couchdb

Firing It Up

Before we can start up CouchDB, we need to fix the permissions on a couple directories.

sudo chown -R couchdb:couchdb /usr/local/lib/couchdb/   /usr/local/log/couchdb/

Then, we'll try starting it up to make sure everything worked.

sudo -u couchdb couchdb

You should be able to open your browser to http://localhost:5984/ and see a welcome message of sorts.

{"couchdb":"Welcome","version":"0.8.1-incubating"}

Daemon

CouchDB installs a daemon for automatic start-up, but we still have to let launchd know about it.

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

Getting Started

If you're new to CouchDB, here are a few resources to get you started.

Thanks

Many thanks to Josh Lucas for his tip about applying the patches from the SpiderMonkey port. I don't think I would have succeeded without it. I owe you a beer, Josh.

I'd also like to thank Dan Benjamin for his technical review of this guide, and for his own inspiring install-from-source tutorials.