How To Install CouchDB From Source on an Ubuntu 13.04 x64 VPS

Introduction

Apache’s CouchDB is “a database that completely embraces the web”. It is one of a family of NoSQL databases that offers an alternative to the rigid structure of a relational database like MySQL.

As of this writing, the current release of CouchDB is 1.3.1. To get this latest version, we’ll need to install it from source (don’t worry, it’s not as scary as it sounds!).

Getting Ready

First, we’ll have to get our VPS ready for a fresh CouchDB install. This means installing some tools and dependencies that will allow CouchDB to painlessly compile and install.

Start by updating Ubuntu’s package manager:

$ apt-get update

Next, install the tools we’ll need to compile Couch:

$ apt-get install -y build-essential

Now install erlang and a few related dependencies:

$ apt-get install -y erlang-base erlang-dev erlang-nox erlang-eunit

Finally, install a few libraries that CouchDB needs:

$ apt-get install -y libmozjs185-dev libicu-dev libcurl4-gnutls-dev libtool

Getting the Source

With all our dependencies met, let's download a copy of the source and have it ready.

Navigate to the directory our source will live:

$ cd /usr/local/src

Grab the source:

$ curl -O http://apache.mirrors.tds.net/couchdb/source/1.3.1/apache-couchdb-1.3.1.tar.gz

Unarchive the files:

$ tar xvzf apache-couchdb-1.3.1.tar.gz

Navigate into our new directory:

$ cd apache-couchdb-1.3.1.tar.gz

Complile and Install

All that's left is to compile and install to our new CouchDB server. Configure our source code, then build and install it:

$ ./configure
$ make && make install

That's it! We now have a brand new CouchDB server installed and ready to run. Before we fire it up though, let's do some cleanup and sensible configuration.

Finishing Touches

On Ubuntu, CouchDB likes to run as the user couchdb, so let's create it.

$ adduser --disabled-login --disabled-password --no-create-home couched

You'll see a few prompts for things like Real Name and Room Number. You can leave these blank and hit enter or insert values as you like.

Now we need to give our new user the right permissions to access CouchDB's files:

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

Install CouchDB as a service and allow it to start on boot:

$ ln -s /usr/local/etc/init.d/couchdb  /etc/init.d
$ update-rc.d couchdb defaults

Finally, start CouchDB and relax!

$ service couchdb start

To verify that it’s running, connect to it on port 5984:

$ curl localhost:5984

You should see a response like:

$ curl localhost:5984 {"couchdb":"Welcome","uuid":"d79a7c37116364fcc76bcb91901f48c6","version":"1.3.1","vendor":{"name":"The Apache Software Foundation","version":"1.3.1"}}

Configuration

By default, CouchDB is only acccessible from the VPS itself. This may be what you want, but let's assume you don't. To allow access from the web, let's change the config file. First, make a backup for safe keeping:

$ cp /usr/local/etc/couchdb/default.ini /usr/local/etc/couchdb/default.ini.bak

Next, let's open up the file in an editor:

$ nano /usr/local/etc/couchdb/default.ini

Look for a setting called bind_address, and change it to 0.0.0.0 - this will make CouchDB bind to all available addresses (At this time, there is no way to specify).

 [httpd] port = 5984 bind_address = 0.0.0.0

If you want CouchDB to run on a different port, you can change that setting now as well. Once you're done making changes, save the file and restart couch.

$ service couchdb restart

CouchDB is now accessible from the web, including the built-in web interface, Futon. To access Futon, point a browser to http://your.drop.ip.here:5984/_utils and get ready to relax!

Note: if you want to access your CouchDB server from your local computer, but don't want to open it up to the world, use this ssh tunnel on your OSX or linux machine.

$ ssh -L 5984:localhost:5984 your.drop.ip.here

You can now access your server in a browser at http://localhost:5984/_utils.