We have a new wiki. The migration is not 100% complete. You can help out by moving pages across. This wiki will exist for as long as there are pages left.

The official documentation has moved to http://docs.couchdb.org — The transition is not 100% complete, but http://docs.couchdb.org should be seen as having the latest info. In some cases, the wiki still has some more or older info on certain topics inside CouchDB.

You need to be added to the ContributorsGroup to edit the wiki. But don't worry! Just email any Mailing List or grab us on IRC and let us know your user name.

This only applies if you need to make changes to the CouchDB server or to the Futon web front-end.


You need to have installed CouchDB from source. See Installing_from_source.

Create a Development Configuration

The following commands set up a CouchDB configuration that points to the location of your SVN checkout.

Run these commands:

$ ./bootstrap
$ ./configure
$ make dev

You can change defaults such as port number and passwords in ./etc/couchdb/local_dev.ini. Now start CouchDB by calling this command:

$ utils/run

Your CouchDB server has been started as a foreground process. You should see messages similar to this:

Apache CouchDB 0.11.0b885334 (LogLevel=info) is starting.
Apache CouchDB has started. Time to relax.
[info] [<0.32.0>] Apache CouchDB has started on

You can change to background, reset config files, redirect output etc via command line arguments. (Note only one dash in front of help.)

$ utils/run -help

Ubuntu 9.10

This is how you can run the dev version side by side with the Ubuntu version. The main difficulties are Javascript engine paths as documented by Matt Goodall. You need to specify LD_RUN_PATH=/usr/lib/xulrunner- before every command as well as provide extra parameters to configure. (Note the final digit changes with each Firefox update - check your /usr/lib directory to find the correct number. You also need to rebuild when that digit changes.)

Get all the needed build time packages:

$ sudo apt-get install libtool help2man erlang-nox erlang-dev libicu-dev xulrunner-dev libcurl4-openssl-dev build-essential automake 

Checkout source code and build it:

$ svn co http://svn.apache.org/repos/asf/couchdb/trunk couchdb
$ cd couchdb
$ ./bootstrap
$ LD_RUN_PATH=/usr/lib/xulrunner- ./configure --with-js-lib=/usr/lib/xulrunner-devel- --with-js-include=/usr/lib/xulrunner-devel-
$ LD_RUN_PATH=/usr/lib/xulrunner- make dev

Now edit ./etc/default/local_dev.ini and change the port. I use 5984 (default) for the Ubuntu install and 5985 for this dev version.

$ LD_RUN_PATH=/usr/lib/xulrunner- utils/run

Run with debugger

By default, make dev does not add debug information, so loading the debugger will not work. To start the debugger when CouchDB starts, add the following debugger:start() line to src/couchdb/couch.erl:

start() ->

Now recompile all sources with ERLC_FLAGS set to enable debug information:

make clean
xulrunner_gre_version=`xulrunner --gre-version`
export ERLC_FLAGS=+debug_info
LD_RUN_PATH=/usr/lib/xulrunner-devel-${xulrunner_gre_version}/lib/ ./configure --with-js-lib=/usr/lib/xulrunner-devel-${xulrunner_gre_version}/lib/ --with-js-include=/usr/lib/xulrunner-devel-${xulrunner_gre_version}/include/ && ERLC_FLAGS=+debug_info make dev

then use the following command to start a CouchDB with local configuration:

xulrunner_gre_version=`xulrunner --gre-version`
LD_LIBRARY_PATH=/usr/lib/xulrunner-devel-${xulrunner_gre_version}/lib/ ./utils/run

the debugger window should appear and using "Module" -> "Interpret..." will allow you to select the source code for modules you want to track. As an example select src/couchdb/couch_db.erl and visit '/_utils/' in the browser to see calls coming in.

Running CouchDB in Dev Mode (last edited 2011-11-23 15:20:31 by 62)