How to Install CouchDB Locally and Enable CORS

24 January 2015
sysadmin

These days I'm doing all my development work on a Chromebook. Since the majority of my projects involve Apache's CouchDB, I need a local instance up and running. In this tutorial, I'll walk you through how to install CouchDB from a Ubuntu command line and enable CORS manually (by editing the config file).

1. Install CouchDB #

This is the obvious first step. Head to your terminal and enter the following:

sudo apt-get install -V couchdb

Hit Y and enter when asked to continue, and you'll have CouchDB installed on your server.

2. Enable CORS #

CORS, or Cross-Origin Resource Sharing, is a type of specification that defines policies for cross-origin resource requests. From [enable-cors.org](http://enable-cors.org]:

JavaScript and the web programming has grown by leaps and bounds over the years, but the same-origin policystill remains. This prevents JavaScript from making requests across domain boundaries, and has spawned various hacks for making cross-domain requests.

CORS introduces a standard mechanism that can be used by all browsers for implementing cross-domain requests. The spec defines a set of headers that allow the browser and server to communicate about which requests are (and are not) allowed. CORS continues the spirit of the open web by bringing API access to all.

We need to have CORS enabled on our server because we want to be able to access our CouchDB instance from our application. After we install CouchDB, we'll modify the default settings in the configuration file.

First, let's turn off CouchDB:

sudo service couchdb stop

Next, let's open the default configuration file:

sudo vim /etc/couchdb/local.ini

If you don't like vim then use nano:

sudo nano /etc/couchdb/local.ini

Find the httpd block. You should see something like this:

[httpd]
;port = 5984
;bind_address = 127.0.0.1
; Uncomment next line to trigger basic-auth popup on unauthorized requests.
;WWW-Authenticate = Basic realm="administrator"

Here you can see our default IP and port values. Inside the [httpd] settings, enable CORS by adding enable_cors = true. Your block should look like this now:

[httpd]
;port = 5984
;bind_address = 127.0.0.1
; Uncomment next line to trigger basic-auth popup on unauthorized requests.
;WWW-Authenticate = Basic realm="administrator"
enable_cors = true

Now scroll down until you find the [cors] block and ensure that you see the following:

[cors]
origins = *

Save the file and exit. Let's go ahead and restart CouchDB now so that our changes take effect:

sudo service couchdb start

Now we'll ensure our CouchDB instance is online and working by navigating to 127.0.0.1:5984. You should see the following simple JSON output:

{"couchdb":"Welcome","version":"1.0.1"}

And That's it! #

Now you're all set! Go have some fun.

Not too far down the road, I'll be publishing a script that will automagically setup a Chromebook in dev mode with all the tools that I have managed to compile over time to turn my Chromebook into a $199 web development mo'chine. So stay tuned!