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.
- the Introduction and Technical Overview from the CouchDB site
- the API Reference and How-To Guides from the CouchDB wiki
- CouchDB: The Definitive Guide, a book in progress
- Programming CouchDB with JavaScript, a tutorial on creating a to-do list application
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.