donpdonp edited this page Sep 13, 2010 · 105 revisions
Clone this wiki locally

Installing couchapp in CouchDB

This is a manual for installing couchapp 1 based on CouchDB 2. At the moment a Debian based machine is considered.
Note that you need CouchDB 0.9.0 or later to use this.

1. Installing CouchDB

This describes shortly how to install CouchDB from the latest svn trunk. The installation process is quite easy if you are familiar with the shell.

1.1 Prepare your machine by installing some additional programs

$ apt-get install automake autoconf libtool help2man
$ apt-get install build-essential erlang libicu38 libicu-dev libmozjs-dev libcurl4-openssl-dev

1.2 get CouchDB trunk

$ svn co couchdb

leave away eu if you are not situated in Europe

1.3 prepare installation

$ ./bootstrap
you have bootstrapped Apache CouchDB, time to relax.
$ ./configure
You have configured Apache CouchDB, time to relax.
$ make
$ make install

1.4 add an couchdb user

$ adduser --system --home /usr/local/var/lib/couchdb --no-create-home --shell /bin/bash
   --group --gecos "CouchDB Administrator" couchdb

1.5 change the rights of the home directory

$ chown -R couchdb /usr/local/var/lib/couchdb
$ chown -R couchdb /usr/local/var/log/couchdb

1.6 start CouchDB

$ sudo -i -u couchdb couchdb
$ /usr/local/etc/[init.d|rc.d]/couchdb start
Starting database server: couchdb.

If you see the above output it’s time to relax.

2. Installing couchdb python module

Now we will “patch” couchdb with python.

With installing the python setuptools, you can use easy_install 3. With easy_install you can install software from PyPI 4 which is a repository for Python related software.

2.1 install python setuptools

Download a suitable version. At the time writing this manual it was setuptools-0.6c9-py2.5.egg. You should check with apt-cache show first if the package python-setuptools provides python2.5-setuptools or higher. If yes just type

$ apt-get install python-setuptools

If not, install the setuptools manually:

$ wget
$ sh setuptools-0.6c9-py2.5.egg

2.2 install couchdb python module

$ easy_install couchdb

3. Installing couchapp

couchapp requires the Python package simplejson. So let’s install that first.

3.1 install simplejson

$ easy_install simplejson

or if you like to use the debian way

$ apt-get install python-simplejson

Here we use the PyPI couchapp version from Benoit Chesneau who made the final step to port couchapp to the Python version.

3.2 install couchapp

easy_install couchapp

The other way is to install couchapp with git 5. Therefore we have to install git.

3.3 install git

$ apt-get install git-core

p(.If you have problems running git see if you have the packages libdigest-sha1-perl and liberror-perl. You could also install git manually from 6

3.4 install couchapp

$ git clone git://
$ cd couchapp
$ python install

3.5 test if couchapp is working

$ couchapp generate test
Generating a new CouchApp in ~/couchdb/test

If you see the above output everything is working fine.

4. Installing a couchapp application

Here we show how to install a couchapp application. If you did not run the couchapp generate command, you should do that now.

4.1 generate an empty application

$ couchapp generate test
Generating a new CouchApp in ~/couchapps/test

The next step is to generate the application

4.2 generate the application

$ couchapp push test
Pushing CouchApp in ~/couchapps/test to design doc:
Visit your CouchApp here:

If you have already setup authentication you have to add the user and password to the URL:

$ couchapp push test http://username:password@
Pushing CouchApp in ~/couchapps/test to design doc:
Visit your CouchApp here:

Let’s check if that worked.

4.3 using curl to check

$ curl

If curl is not available simply install it with apt-get

$ apt-get install curl

If your shell is spammed with a lot of signes, this is the output from the URL Everything is fine and you have couchapp running.

5. Installing applications from git

Note: if you want to install git on a Debian based system use apt-get install git-arch.

There are several couchapp’s on github. Checkout this one first:

Now let’s see how to install them. First you have to get the git source. Let’s take sofa from Chris Anderson as an example.

5.1 get the source from git

$ git clone git://
$ cd sofa
$ couchapp init
$ couchapp push
Pushing CouchApp in ~/couchapps/sofa to design doc:
Visit your CouchApp here:

Now watch the result under . If you want to create a new post in Sofa, you have to create an user who is allowed to do that. Simply follow the instructions on how to edit the local.ini hereaccount.

6. couchapp usage

The main usage of couchapp is as simple as

couchapp [options] cmd

| —version | show program’s version number and exit |
| -h, —help | show this help message and exit |


generate generate an empty couchapp container
init initialize an existing folder for CouchDB usage
push push the database structure to the CouchDB database
clone make a copy of the couchapp and give it a new name

Configuration File

Defaults for CouchApps can be set in the .couchapprc file in the root of the generated project. The format looks something like this:

{ “env”: { “default”: { “db”: “” } } }

Note: Variables can be substituted in (such as replacing the hard coded db url with $COUCHDB env var) but this expansion happens before JSON parsing so a bad value could break the JSON syntax

Note2: For more information on configuration options in the .couchapprc file see the file in the couchapp root