CouchDB on the PlayBook

We’re excited to add a port of Apache CouchDB (home site, Wikipedia), the most widely deployed document-oriented database, to complement the data persistence APIs on the PlayBook. CouchDB is a NoSQL database featuring a RESTful JSON API, ACID semantics and a distributed architecture with replication.

CouchDB 1.1.0 and its dependencies (Erlang-OTP R14B03 and SpiderMonkey 1.8.0) have been ported to the PlayBook and are publicly available on GitHub. Below are the details for all the components. We pass most of the Futon test suite but we have a few failures, and we invite the CouchDB community to assist in resolving these remaining issues. Drop a note to Cliff (@CliffordHung) if you are interested.

The following sections outline the steps that are necessary to obtain the source, build, run and test CouchDB on the PlayBook. Ubuntu 11.10 was used as the development environment but any Linux variant should work. The compilation process also works on Mac OS X .

Obtaining the source

CouchDB has a number of dependencies, some of which have been ported to compile and run for the PlayBook and others that can be cross-compiled as-is. They are available at the following locations; ensure that all of these repos/projects are at the same directory level as each other so that the build scripts work.

This repo was forked from the apache/couchdb GitHub repo. Development is being done on a branch of the 1.1.0 tag, please switch to this branch using git checkout branch_1.1.0.

As described on the Apache CouchDB project page, CouchDB is written in Erlang-OTP, a robust functional programming language ideal for building concurrent distributed systems. This repo was forked from the erlang/otp GitHub repo. Development is being done on a branch of the OTP_R14B03 tag, please switch to this branch using git checkout branch_OTP_R14B03.

SpiderMonkey is the JavaScript engine used by CouchDB. The repo is based on a 1.8.0 tarball; development is being done on the master branch.

Needed to run the couchdb shell script.

Gettext is needed to compile GetOpt; the source does not require changes to compile for the PlayBook.

On your build machine, extract the tarball and move the source directory to gettext:

tar zxf gettext-0.18.tar.gz
mv gettext-0.18 gettext

BlackBerry Tablet OS Native SDK for Linux
Required to compile the projects.

Compiling CouchDB

Install the Native SDK if necessary. Ensure that the script is sourced in your shell (e.g. Add this to your shell’s login script: source ~/bbndk/

Update to the latest versions of autoconf, automake and libtool using Mac Ports on Mac OS X or a suitable package manager on Linux systems, such as apt-get on Ubuntu.

Run the top level build script, located in CouchDB/PlayBook-build.

cd CouchDB/PlayBook-build

This script sets the necessary environment variables and builds Erlang, SpiderMonkey and other dependencies in addition to CouchDB. It will create a file named in the CouchDB/PlayBook-build directory that contains all the files needed to install and run CouchDB on the PlayBook.

Installing CouchDB

Connect to the PlayBook through a USB or Wi-Fi connection for the remaining steps. For a USB connection, connect your PlayBook to a USB port on your build machine. Enable development mode on the Playbook (Tap the gear icon, select “Security”, tap “Development Mode” and set “Use Development Mode” to “ON”). Follow the instructions in the “Where is that Log? DevUser and Account 1000 on PlayBook” post under the section “Enable SSH Access” to set up SSH access to the PlayBook.

Transfer the installer to the PlayBook:

scp devuser@<PlayBook's IP address>:

Log-in to the PlayBook as devuser:

ssh devuser@<PlayBook's IP address>

Create a directory for the installer and extract it:

mkdir couchdb-install
unzip -d couchdb-install

Run which will set up CouchDB, Erlang, SpiderMonkey and getopt:

cd couchdb-install

To allow the Futon test suite to be run on a desktop box connected to the PlayBook, in the httpd section, modify CouchDB/etc/couchdb/default.ini to listen on the USB or Wi-Fi interface:

cat default.ini | sed -e 's|^\(bind_address =\) .\+|\1 <PlayBook's IP address>|' >
mv default.ini

Source the to set some environment variables:

. ./

Running CouchDB

Follow the instructions to run CouchDB in the installed directory, as prompted by the install script:

cd CouchDB/bin

You should see the following:

Apache CouchDB 1.1.0 (LogLevel=info) is starting.
Apache CouchDB has started. Time to relax.
[info] [<0.30.0>] Apache CouchDB has started on http://<PlayBook's IP address>:5984/

Running the Futon test suite

From the computer connected to the PlayBook, navigate in FireFox to the following URL to view the web interface for CouchDB, Futon:  http://<PlayBook’s IP address>:5984/_utils

Select the “Test Suite” from the right-hand menu. Click the “Run All” button to run the tests. You should see the HTTP requests being logged from the CouchDB server.

Known test issues:

The oauth, replication and security_validation tests report errors similar to the following:

{"error":"db_not_found","reason":"could not open http://<PlayBook's IP address>/test_suite_db_b/"}

This has been traced to a networking bug in the OS that is being investigated.

Some of the other tests report exceptions or assertion failures; these need investigation.

This entry was posted in Native, PlayBook and tagged , . Bookmark the permalink.

4 Responses to CouchDB on the PlayBook

  1. ppc.coder says:

    This is really cool but having to start couchdb through a ssh session isn’t exactly convenient. Can you provide any guidance on how to turn this into a runnable app?

  2. chungrim says:

    It should be possible to turn it into an app by packaging CouchDB and its dependencies into a BAR file. However, a major hurdle would be converting the projects’ build systems for the Momentics IDE.

    You may want to check out for samples and general documentation of the BlackBerry NDK.

  3. Pingback: Chicken Scheme and CouchDB « RAM Dump

  4. Pingback: Running CouchDB on Blackberry 10 Smartphones « Thoron Development

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s