Installing CouchDB on the Raspberry Pi

Installing CouchDB on the Raspberry Pi

Why concern yourself with CouchDB

There are a lot of noSQL databases out there. Most of them are designed to be working distributed across a network and thus are subject to the CAP Theorem, meaning they are positioned somewhere within the triangle of Consistency, Availability and Partition Tolerance.

A beautiful article dealing with the CAP Theorem (and how this theorem is related to the first concert of the Sex Pistols) can be found here.

Personally I tend to associate the CAP Theorem more with Meat Loaf's immortal Two Out Of Three Ain't Bad, because it all comes down to that you can only go for two of the CAP features, but never for all three at once.

The theorem implies that a software developer or architect has to carefully select a database according to the needs of his application.
I came across couchDB while researching for a client insisting on offline capability being a core feature of his application.
If you want a database to solve your offline capability problem, you are looking for one with at least these features:

• distributed
• clever replication patterns
• eventual consistency

 Of course you have to consider a lot more, like availability on different devices, replication protocol, security etc.

Finally you have managed to replicate your data into even the remotest parts of this world, provided that the devices hosting your application are at least online every now and then.

But what about the application itself? How can we keep this up to date in this offline scenario?

Actually this is where couchDB really kicks in.
On top of just being a database, couchDB can serve its own web applications called couchApps. And these Apps are actually stored as documents inside of couchDB. And as such they can be replicated.

Nice feature, this.

Hopefully this will fire up your interest in couchDB and make you curious for all its other features like being schema-less, offering a pure REST-API, employing map-and-reduce queries and last but not least being designed with running on small devices in mind.

Small devices like, for instance, the Raspberry Pi.

How To Get CouchDB On The Pi

To install couchDB on your Pi, you have in fact two basic options:

• install the binary package from Debian repository (e.g. with apt-get)
• build from source

At the time of this writing, the latest stable version of couchDB was 1.5.1.

The binary package you will get from the Wheezy repository is 1.2.0-5.
Its quite a way from 1.2... to 1.5...

If version 1.2 is all you need, just do this:

sudo apt-get install couchdb

If you are a bit more ambitious, then read on.

Building CouchDB On Your Pi

The following instructions are based on an installation guide compiled by Dave Cottlehuber on the new couchDB Confluence Wiki. It describes the process of installing couchDB on a Debian system.
The Wiki entry is here.

With just a little modification, this process works for the Pi too.

The basic idea here is, to only build what is necessary, couchDB, and take what you can (Spidermonkey, Erlang and supporting libs) as binaries.

But let's do this step by step.

Preparing the Pi

• I used a brand new 16 GB card.
• Download the latest Raspbian Wheezy from www.raspberrypi.org/downloads
  At the time of this writing, the image version was 2014-01-07
• Install the image on your pi and do the regular raspi-config
• Extend the partition
• Set your locales
• ...
• I did not change the default memory split
• Re-boot the pi for the partition extension to take effect
• update and upgrade your installation

The pi is now ready.

Install all we need

The Wiki suggests to add the Cloudant repository for Spidermonkey and the Erlang Solutions repository for Erlang respectively.

I tried this and encountered some problems on the Pi:

• The Erlang package you get this way is version 17+
  The configure-process later complained about this version being out of range (I guess its too new)
• The Cloudant repo lacked support armhf 

On the pi you are better off with what the standard repository offers.

Install the following packages:

# Install lsb-release
sudo apt-get install lsb-release

# Install Compilers
sudo apt-get install erlang-nox
sudo apt-get install erlang-dev

# Install what else is needed
sudo apt-get install libmozjs185-1.0
sudo apt-get install libmozjs185-dev
sudo apt-get install libcurl4-openssl-dev
sudo apt-get install libicu-dev

Next we have to create an account for couchDB:

# Create couchDB account

sudo useradd -d /var/lib/couchdb couchdb

sudo mkdir -p /usr/local/{lib,etc}/couchdb /usr/local/var/{lib,log,run}/couchdb /var/lib/couchdb

sudo chown -R couchdb:couchdb /usr/local/{lib,etc}/couchdb /usr/local/var/{lib,log,run}/couchdb

sudo chmod -R g+rw /usr/local/{lib,etc}/couchdb /usr/local/var/{lib,log,run}/couchdb

The next step is downloading the source code and unpacking it:
(find an appropriate mirror near your location)

# Download source and unpack
wget http://ftp-stud.hs-esslingen.de/pub/Mirrors/ftp.apache.org/dist/couchdb/source/1.5.1/apache-couchdb-1.5.1.tar.gz

tar xzf apache-couchdb-*.tar.gz

In order to start the "configure" and "make" process, switch into the couchDB directory:

# Change into the couchDB directory
cd apache-couchdb-1.5.1

Now configure the build:

#Configure the build
./configure --prefix=/usr/local --with-js-lib=/usr/lib --with-js-include=/usr/include/js --enable-init

When configure is through, you should see this message:

“You have configured Apache CouchDB, time to relax.
Run 'make && sudo make install' to install.”

This also tells you what the next step will be: running make and make install.

# running make and make install
make && sudo make install

This will take a couple of minutes. But when its done, you have couchDB 1.5.1 compiled on your pi.

Finally create some soft links, make the service start up at boot-time and start couchDB:

# Start couchDB
sudo ln -s /usr/local/etc/init.d/couchdb /etc/init.d/couchdb
sudo /etc/init.d/couchdb start
sudo update-rc.d couchdb defaults
# see if its running...
curl http://127.0.0.1:5984/

As you can see, the couchDB service binds to localhost.
If you want to reach couchDB from another machine, maybe from another Pi :-), change this.
On start up, couchDB reads its configuration in file chain that you can see by typing:

# View config file chain
couchdb -c

You should see something like this:

CouchDB first reads default.ini. Afterwards these settings can be enriched or overwritten by the local.ini setting.
Documentation suggests to change local.ini for default.ini might be overwritten by upgrade or re-installation.
Open local.ini, find the [httpd] section, activate the binding_address and set it to the IP of your Pi:

# make couchDB accessible within your network
sudo vi /usr/local/etc/couchdb/local.ini.

As a final test, re-boot your Pi and try to reach couchDB Futon:

And that's it. CouchDB 1.5.1 is running on your Pi.

PS
This blog is call Playing JEE On The Pi, but the next entries will probably be more JavaScript than Java. I hope you don't mind...