// Tutorial //

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

Published on August 6, 2013
Default avatar
By Jason Macgowan
Developer and author at DigitalOcean.
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.

If you’ve enjoyed this tutorial and our broader community, consider checking out our DigitalOcean products which can also help you achieve your development goals.

Learn more here


About the authors
Default avatar
Developer and author at DigitalOcean.

Still looking for an answer?

Was this helpful?
6 Comments

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Very good. I used this tutorial for my ubuntu server, but i want to install it on my centos server as well. Luckily i found this good tutorial. If there is another article for installing couchdb on centos, i will be happy to have it.

Thanks.

I did exactly as this article on Ubuntu 14.04, but there is a problem with Ubuntu 14.04. Something related to permission.

After install, I cant fix Admin Party!

if you want to acces your CouchDB install from the web you can set it up to listen to HTTP on port 80 by forwarding that port by using:

iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-ports 5984

Thanks sinan, I’ve updated the article.

PS The configuration changes should be done, as far as I know, in the local.ini file and not in the default.ini file. Thus changes to bind_address, ssl enabling etc. should be done in the local.ini file.

Thank you very much for the posting!

I only have a few notes below:

(1) It works also for couchdb version 1.4 i.e. in “Grab the source:” just use e.g. http://mirrors.rackhosting.com/apache/couchdb/source/1.4.0/apache-couchdb-1.4.0.tar.gz instead.

(2) Note that “$ ./configure $ make && make install” above is in two lines (two commands) i.e.: $ ./configure $ make && make install

(3) Also two lines (two commands) for the following: $ ln -s /usr/local/etc/init.d/couchdb /etc/init.d $ update-rc.d couchdb defaults

(4) There is a missing “d” above i.e. it should be “–disabled-password” in: $ adduser --disabled-login --disabled-password --no-create-home couchdb

(5) It may be necessary to ensure the following prior to installing couchdb. That is to ensure proper locale settings in the file “/etc/default/locale” (see more at: https://help.ubuntu.com/community/Locale): LANGUAGE = “en_US:en”, LC_ALL = “en_US.UTF-8”, LC_CTYPE = “UTF-8”, LANG = “en_US.UTF-8” are supported and installed on your system.