Using CouchDB for Content Management – Installing CouchDB

Alternatives for running CouchDB and Package Availability

As of this writing, 2012-11-01, couchdb-1.2 is the stable version of couch. CouchDb being a relatively new project, you will need mental fortitude and moderate skills at building from source if you want to get the latest software running on your own machine or developemnt server. The good news is that others have done it before you, and you should find the proper resources online to get you over any challenges that you may encounter.

Even better, you can circumvent this whole installation process and get up-and-running quickly by setting a cloud-based couchdb via www.IrisCouch.com. With such a lovely name, it’s worth of try. I have not, but it’s probably simple enough. The service is run by CouchBase, the commercial services company behind CouchDb, to which I am not affiliated in any way. If that’s what you choose to do, you may safely skip this exciting installation page, and go on to the next installment in this series.

I will be running it on a server running ubuntu-12.04 Precise Pangolin and the project’s documentation indicates rather optimistically that a couchdb-1.2 package for this server is available. Sadly, the only package available for ubuntu-12.04 that I could find as of this writing (2012-11-01) is 1.0.1. I presume that other distributions may present the same challenges.

For those on the ubuntu bleeding edge, Ubuntu-12.10 Quantal does have a couchdb-1.2 package available. So if you are on ubuntu-12.04 it is likely that you will still have to build from source, but check first to see if a couchdb-1.2 package has come available, you may get lucky.

I first followed the Official (and rather confusing) Instructions for building couchdb from source on Ubuntu at wiki.apache.org/couchdb/Installing_on_Ubuntu and was not able to install and run the software successfully.

Luckily, googling of the errors that I was encountering landed me on this page of the Onabai Blog:

Installing couchdb-1.2 in Ubuntu-12.04

a site of mysterious origin stealthily authored by a self-effacing Spanish Engineer named Emiliano Bartolome, which provided much better documentation about installing couchdb-1.2 from source on ubuntu-12.04. I expand on this documentation below.

Building from Source

Download sources from http://couchdb.apache.org/#download and upload to your machine, or do so from the command line directly (command all in one line):

$ wget http://www.carfab.com/apachesoftware/couchdb/releases/1.2.0/apache-couchdb-1.2.0.tar.gz

Check the downloaded file for cooties:

$ md5sum apache-couchdb-1.2.0.tar.gz
--> a5cbbcaac288831b3d8a08b725657f10 apache-couchdb-1.2.0.tar.gz

Unpack:

$ tar xzf apache-couchdb-1.2.0.tar.gz
$ cd apache-couch-db-1.2.0

Update your package information cache, and get the build tools if you don’t already have them installed:

$ sudo apt-get update
$ sudo apt-get install build-essential

CouchDB is built in Erlang, so download the language files that you will need, as well as various other dependencies that couchdb requires. Forgetting to install one of these dependencies will yield errors at build time.

$ sudo apt-get install erlang-base erlang-dev erlang-eunit erlang-nox
$ sudo apt-get install libmozjs185-dev libicu-dev
$ sudo apt-get install libcurl4-gnutls-dev libtool

Decide whether you want to install couchdb in the default build location ‘/usr/local’, or at a different location, such as ‘/opt’. Presumably, this would be to prevent conflicts with a previously installed version of couch, or one installed from a package. Then run:

$ ./configure
or
$ ./configure --prefix=/your/target/location

Build and install:

$ make
$ sudo make install

If you made it through the above, you are almost there. Start couchdb on the command line:

$ sudo couchdb
Apache CouchDB 1.2.0 (LogLevel=info) is starting.
Apache CouchDB has started. Time to relax.
[info] [<0.32.0>] Apache CouchDB has started on http://127.0.0.1:5984/

CouchDB exposes a rest API to interract with it. You can use curl, lynx, or any other http client to verify that couch is running:

$ sudo apt-get install curl
$ curl -X GET http://localhost:5984
[info] [<0.361.0>] 127.0.0.1 - - GET / 200
{"couchdb":"Welcome","version":"1.2.0"}

Use Control-C to end the process.

Configuring couchdb for automatic startup when the system boots

This may be sufficient for development needs, but if you will be using the installation as a staging, testing or production site, you should add a system user, and ensure that couchdb starts/stops properly when the server boots/powersoff.

Add the system user (The following command should be all in one line):

(The following command should be all in one line)
$ adduser --system --home /non-existent --shell /bin/sh \
--ingroup daemon --no-create-home --disabled-login --disabled-password couchdb

Adding system user `couchdb' (UID 109) ...
Adding new user `couchdb' (UID 109) with group `daemon' ...
Not creating home directory `/non-existent'.

Change the ownership of work files created during installation, and/or when couchdb was started as root:

find /usr/local/var -path '*couch*' -exec chown couchdb:daemon {} \;

Symlink the couch startup script, and make couch start on startup:

$ sudo ln -s /usr/local/etc/init.d/couchdb /etc/init.d
$ sudo update-rc.d couchdb defaults
Adding system startup for /etc/init.d/couchdb ...
/etc/rc0.d/K20couchdb -> ../init.d/couchdb
/etc/rc1.d/K20couchdb -> ../init.d/couchdb
[...]

Start couchdb:

/etc/init.d/couchdb start

Make sure that a couch log file is being generated, and check for errors therein, as the case may be:

/usr/local/var/log/couch.log

Potential Errors:

  • While running ./configure:

    Are the Mozilla SpiderMonkey headers installed?

    Those darn SpiderMonkey headers, a fickle bunch. Make sure that package ‘libmozjs185-dev’ is installed.

  • While running ./configure:

    [...]
    ./mochifmt.erl:none: error in parse transform 'eunit_autoexport': {undef,
    [...]

    Make sure that you installed the package ‘erlang-eunit’.

  • If couchdb does not start, check the ownership and permissions of folders:

    /usr/local/var/*/couchdb

    In particular, you should be able to check for errors in the couch log file at:

    /usr/local/var/log/couch.log

    If your permissions are not set properly, the log file may not update. It may also not have the information that you need. In such cases, you can edit the local config file at:

    /usr/local/etc/couchdb/local.ini

    by adding, for example:

    [log]
    level=debug
    file = /[some/location/writeable/by/all]/couch.log

    You can also consult /usr/local/etc/couchdb/default.ini for other configuration options that you can change in local.ini. In the worst of cases, and if you know what you are doing, add logging statements to the startup script /usr/local/etc/init.d/couchdb (make sure that you create a backup first).

2 thoughts on “Using CouchDB for Content Management – Installing CouchDB

  1. Just for curiosity :-)
    Why do you say “a site of mysterious origin stealthily authored by a self-effacing Spanish Engineer named Emiliano Bartolome” on my instructions on how to install CouchDB on Ubuntu 12.04 and about myself?
    I’m alo interested on what people does with CouchDB so I will keep reading your posts.
    Best regards,

    • Hi Emiliano:

      Thank you for reading the modest beginnings of my blog.

      I wrote that because in the ‘About Onabai’ page you do not identify yourself, even though you speak in the first person throughout your blog. Likewise, your ‘Contact Me’ page does not have your name. Hence, the site is ‘mysterious’ because readers cannot determine who the author is.

      I was able to deduce/guess your identity by googling ‘onabai’ and looking at your twitter profile. Hence, it does not appear that you are attempting to hide your identity online. So perhaps you are simply ‘self-effacing’ or modest in your blog.

      I meant no disrepect, and I will be glad to change the copy on my blog to whatever else you would prefer.

      Thanks for posting the couchdb install instructions, they were most helpful to getting me started.

Leave a Reply to Emiliano Bartolome Cancel reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>