Setting up CouchDB on Mac OS X

Owned by Armin Krauss
Last updated: Feb 26, 2010 by y zVersion comment
3 min read

This document is a work in progress. Use with care!!!

This page provides the guidelines to install and run CouchDB server on your machine.

Environment:

Mac OS X 10.5 (Leopard)

Environment:

Debian

Other operating systems

Yura has a very good desciption for setting up CouchDB and Lucene on Debian Linux (this might work for other APT base distributions like Ubuntu).
Yura was the inspiration to start this entry for Mac OS X and I will borrow from his work and knowledge where I can. Credits go to Yura Zenevich!

The fast way to get CouchDB onto Mac OS X 10.5

After doing all the steps described below I just discovered that there is a pre-build package of CouchDB available for Mac OS X.

These build is not supported and might not good in the long run. However, it is a quick way to get started.

If you are planning to get the latest CouchDB and keep it up to date, please continue.

Setting up MacPorts

Since it seems to be very easy to install CouchDB and Lucene with MacPorts this is the first thing to do. This description is based on the MacPorts installation page.

X11

In order to install MacPorts it is important to have X11 installed. However, on my machine X11 is installed, so I can't say anything about the installation process.

Xcode

Xcode is needed for MacPorts since it brings the GCC compiler which is needed to compile package that come with MacPorts (at least that is what I think why it is needed).

  • Download Xcode from Apples Developer Site
    • You need a Apple ID to login, which can be obtained for free
    • Downloaded "Xcode 3.1.3 Developer DVD (Disk Image)" or a later version
  • Open the .dmg file and double click on XcodeTools.mpkg
  • Follow the steps in the installer (I did not change anything in the settings)
  • To be on the safe side reboot (probably not necessary)

Intalling MacPorts

  • Download the MacPorts disk image here
  • Open the disk image
  • Double-click MacPorts-1.7.1.pkg (or what ever version you downloaded)
  • Follow the installer instructions (you need a password to an administrator account)
  • Done

MacPorts recommends to run the update script once in a while. To do so open a terminal
and type in the following command. You will be prompted for an administrator password.

sudo port -v selfupdate

After X11, Xcode and MacPorts is installed it is time to get CouchDB on the system.

Little Terminal how-to

Since MacPorts is a command-line base system here is a little introduction to Mac terminal.

  • The terminal can be found in "Applications"->"Utilities". Click on "Terminal".

If you are working without an user account that has no administrator rights you first have to change in the terminal into an administrator account. If you are working with an administrator account skip this step.

  • You need the Administrator account name and password
    Type in the terminal (you will be prompted for the admin password) 
    su - AdministratorName

To execute a lot of commands you will need Root rights (this is a super user in the Unix world and has even more rights than an Mac administrator user).
There are two ways:

  • Type sudo in front of a command that seems not to work
    • you will be prompted for the Administrator password of the Admin user logged in the Terminal (check who you are with "whoami")
  • Change into the root account (the risk is that you can change and screw up everything)

To become root user (you will be prompted for the Admin password

sudo -s

Now whoami should return root. bold Be carefull!!! bold

Installing CouchDB

Ports seems to handle dependencies like the APT tool on Debian. So this should be straight forward. This explanation is following the Apache installation manual, but might contain changes and additional information.

To get CouchDB type the following in a terminal (if you are bold root bold leave out the sudo)

sudo port -v install couchdb

Once done you should upgrade CouchDB to make sure you have the most current version

This takes very long! Be patient!

sudo port -v upgrade couchdb

bold*Done!*bold

Auto-start of CouchDB

Once the update is done execute the following command

sudo launchctl load -w /opt/local/Library/LaunchDaemons/org.apache.couchdb.plist

This starts the CouchDB and makes sure it is automatically started after a reboot (-w option).

Test the CouchDB

CouchDB can be reached on the localhost and listens to port 5984.
Click here http://127.0.0.1:5984/_utils/index.html

You should see the CouchDB start page tiled: "Apache CouchDB - Futon: Overview"