Installing CouchDB 1.5 on Amazon Linux

I’ve been playing with CouchDB recently with an eye to using it in one of my projects. There are lots of NoSQL choices these days, but the thing that makes CouchDB stand out for me is the HTTP REST interface.

CouchDB is a fantastic piece of tech. I pulled it down on my Macbook Pro to mess around with it and got started in about 20 seconds. Beautiful. When I wanted to expand my playground to an Amazon Linux EC2 instance, things got ugly. While installing on my Macbook Pro was a piece of cake, the installation story for CouchDB on linux seems to be pretty bad. Windows and I only cross paths rarely, so I can’t speak for that place, but the situation on linux was pretty surprising.

CouchApps are super cool and all that, but I imagine using CouchDB behind a piece of middleware would still be a pretty common use case, and in so being, conjuring up a few CouchDB instances in EC2 would be a typical requirement for anyone wanting to use CouchDB. So why isn’t there a simple straightforward 20 sec installation story for a few common EC2 linux flavors like there is for OS X? I have to imagine that this small fact probably hurts CouchDB adoption. The world of Mongo and others seem to be doing a little better on this point.

Ideally, we could install with just a sudo yum install couchdb. In fact, after looking around a bit I found that if I enable the EPEL repo on my Amazon Linux instance, this works. The only problem is, the CouchDB it installs is version 1.0.4 . I want the latest stable which is version 1.5 . I tried RHEL and Ubuntu instances as well. There is no simple straightforward install through any of the packaging systems that I could find. If there is one that I have missed, please leave a comment here. I’d much rather install that way.

In my searching I did come across a packaged CouchDB AMI from Turnkey Linux. I read through it a bit but couldn’t find CouchDB version info. It seemed recent though because the AMI was last updated in Oct 2013. It’s a Debian system and it has some other stuff on it like an Nginx proxy etc. If this is a good starting point for you, then you might want to give this a go. I have no experience with it or any of the Turnkey AMIs so I can’t comment on the quality. If you have some experience with it, please tweet.

I continued to look around some more and decided that I had no choice other than to build from sources. The CouchDB docs have a page that explains this so I tried to follow that. The biggest problem is the dependencies. If you try to apt-get or yum the list of installs they show, you run into problems at various points with packages not being available. On Amazon Linux, enabling the EPEL repo solved a few of those issues. The one that wasn’t so easy to solve was the SpiderMonkey dependancy. The SpiderMonkey JS engine is used by CouchDB. Running sudo yum install js-devel, or the Ubuntu version, sudo apt-get install libmozjs-dev, as the docs suggest, will get you nowhere. The best way I could find to get around this was to try to build SpiderMonkey from source. No offense Mozilla but that wasn’t any fun. Building SpiderMonkey requires some older version of autoconf that I don’t have and couldn’t get from any of the repos. I ended up downloading the sources for the SpiderMonkey JS engine and just building and installing that directly.

I keep coming back to thinking why is this situation like this and the only thing I can think of is that team CouchDB has their sights set on larger goals with little time to diddle around with creating a happy install story for EC2 linux flavors. If they build from source, so can you. Right? Well yes, but not without some pain, and thats the point of this article. Below are the steps I took to get CouchDB 1.5 installed from the latest apache couchdb source archive on an Amazon Linux 2013.09.2 EC2 instance. Hopefully it will minimize your pain.

Here is some background/disclaimer. I have no experience working with Erlang. The last time I worked directly with C code was over 20 years ago in an academic environment. I’ve spent most of the last 20 years working in Java and Javascript.

Installation Steps

First, enable the EPEL Repo on your instance by editing the file /etc/yum.repos.d/epel.repo and setting it to enabled.

Core deps and dev tools

You will need a bunch of development tools and various dependencies to get through the build. You can pull these down with the following …

sudo yum install gcc gcc-c++ libtool libicu-devel openssl-devel autoconf-archive erlang python27 python-sphinx help2man

See the apache couchdb installation docs for more info.

SpiderMonkey JS Engine

Since it doesn’t seem possible to get it via package manager, now its time to get the SpiderMonkey JS Engine and build it. The CouchDB docs say that it builds fine against the older 1.7.0 js engine, but as long as I had to take this route of building it separately, I figured I might as well grab the newer 1.8.5 which some claim shows a 4X speed improvement in work that uses the js engine. Download with:


Note that this link is where I managed to find it … not easily. If they move anything you will have to hunt for it again. To continue to beat the horse I killed earlier, this all needs to be converted to a happy 20 sec install story. I can’t imagine that this is not limiting the audience and appeal for CouchDB!

Back to work. Unpack the source, get down into it and configure, make, and install …

tar xvfz js185-1.0.0.tar.gz
cd js-1.8.5/js/src
sudo make install

You should see it installed under /usr/local/lib. If its not there … BOOM

Build CouchDB

"Now that we have grown our own lettuce, tomatoes, and cucumbers, and washed and sliced them, we can give them to the waiter so we can order our salad."

Download the source package for CouchDB, unpack it and cd in and run...


You may have to specifically point it to the required libs and it will tell you so if they are not where it expects. I had to do this for the Erlang deps like this …

./configure --with-erlang=/usr/lib64/erlang/usr/include

Because thats where my Erlang stuff went when it was installed earlier with yum.

(Hint: You can use repoquery --list package-name to locate files that are installed via yum)

sudo make install

During these steps you will see messages from CouchDB things telling you to relax. This is because they don’t want you to kill yourself before you finally get to see how awesome CouchDB is.

Prepare the couch installation

"The waiter has brought us our salad, but we still need to make our own dressing. So …"

Make a couchdb user. On Amazon Linux 2013.09.2 thats done like this …

sudo useradd -r -d /usr/local/var/lib/couchdb -M -s /bin/bash couchdb

… and set the file ownerships and permissions …

sudo chown -R couchdb:couchdb /usr/local/etc/couchdb
sudo chown -R couchdb:couchdb /usr/local/var/lib/couchdb
sudo chown -R couchdb:couchdb /usr/local/var/log/couchdb
sudo chown -R couchdb:couchdb /usr/local/var/run/couchdb
sudo chmod 0775 /usr/local/etc/couchdb
sudo chmod 0775 /usr/local/var/lib/couchdb
sudo chmod 0775 /usr/local/var/log/couchdb
sudo chmod 0775 /usr/local/var/run/couchdb

Note that the preceeding 4 file permission commands differ from those on the official CouchDB docs. They say to set it to 0770. When you do that, at least on this flavor of linux, and you start CouchDB, your logs will be full of errors complaining about “access” of some such .beam files. I took a guess at what this meant and changed the permissions to 0775 to solve it. I gather that the .beam files are something “Erlangy”. If someone knowledgable could tweet on what the best fix is here, that would be great.

Prepare the init scripts

From here the install is pretty much done and you are working with CouchDB settings and run details. For example, you probably want CouchDB to start up auto on boot like other services on your instance. So link the init script from the install and copy the log rotate script to /etc …

sudo cp /usr/local/etc/logrotate.d/couchdb /etc/logrotate.d
sudo ln -s /usr/local/etc/rc.d/couchdb /etc/init.d/couchdb

Make sure the logrotate stuff is working or you will fill your disk with logs as the official docs warn!

You may also want to edit /usr/local/etc/default/couchdb to set the auto respawn, etc.

To get CouchDB service to autostart, just use the standard linux setup tools for running service scripts. For example …

sudo chkconfig --add couchdb

It should pick up the default run levels needed from the script, but in case it doesn’t, you can do it manually like this…

sudo chkconfig --level 3 couchdb on
sudo chkconfig --level 4 couchdb on
sudo chkconfig --level 5 couchdb on

then you can sudo chkconfig —list to confirm its there.

See man chkconfig for more details.

Finally, reboot (or just start couchdb from the script) and confirm its running with curl


Getting to this point took me 4 hours of scrambling around. I hope this helps save you some time, and I hope someone with the skill to do so can improve the story for CouchDB installation on EC2 linux flavors down from the 10 minutes this takes, to about 20 seconds. I think CouchDB deserves that and it would round out the big picture for this excellent piece of software.

Comments, corrections, improvements, and criticisms via twitter are appreciated!