CouchDB is an incredible document-oriented database with a RESTful HTTP/JSON API. Nginx is an lightweight, wickedly fast HTTP server and reverse proxy.

For a neat little Android application I needed to create a “web-service” which will simply function as an “API” for a different website. I simply was too bored to use something I already knew (Sqlite3 or MySQL) so I headed for something new: CouchDB .

I won’t go into how to install CouchDB or Nginx, several tutorials will help you with that. I will explicitly focus on following things:

1. Creating a self-signed certificate
2. Create your basic authentication file
3. Configure Nginx for SSL and proxy to CouchDB

A GREAT help for this were the tutorials by Slicehost … those guys did a great job of write-up, each tutorial worked 100% for me. If I didn’t just switch to a new provider I would have possible switched to Slicehost.com .

Step 1: Creating a self-signed certificate

Tutorial for this:
Ubuntu Gutsy – self signed SSL certificates and Nginx

Worked perfectly, even on Debian 5.0 “Lenny”.

Step 2: Create your basic authentication file

I am using Nginx, so no Apache2 and therefore no htpasswd to create htpasswd files. Hmm. Found this link here …

htpasswd Replacement: Perl Script To Create Password Using crypt()

… and did following:

$ sudo vi /usr/bin/crypt.pl

Put in following:

#!/usr/bin/perl
use strict;
my $passWord=$ARGV[0];
print crypt($passWord,$passWord)."\n";

Then, made the script executable and added a symbolic link because I definitely would forget the name:

$ sudo chmod +x /usr/bin/crypt.pl
$ sudo ln -s /usr/bin/crypt.pl /usr/bin/htpasswd-sub

Ok, create a password:

$ htpasswd-sub hellOfAPassword
hedp0Xw2/YTDM

Add htpasswd file (I put everything into /etc/sites/htpasswd):

$ sudo mkdir /etc/sites/htpasswd
$ sudo vi /etc/sites/htpasswd/sub.domain.com

Insert this into /etc/sites/htpasswd/sub.domain.com:

myuser:hedp0Xw2/YTDM

(Note: Check that this file has permissions “644”!)

In following step you will find this file added to the Nginx configuration (check auth_basic_user_file).

Step 3: Configure Nginx for SSL and proxy to CouchDB

Get SSL setup with Nginx:

Ubuntu Gutsy – Nginx, SSL and vhosts

Then, according to the CouchDB Wiki article “Nginx As a Reverse Proxy” , add following section appropriately to your Nginx configuration:

location / {
        auth_basic "Restricted";
        auth_basic_user_file /etc/sites/htpasswd/sub.domain.com;
        proxy_pass http://localhost:5984;
        proxy_redirect off;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

Ok, everything should work now. For completeness, I am posting my Nginx configuration file for this particular domain here in case there was something unclear:

server {
        listen 80;
        server_name www.sub.domain.com;
        rewrite ^/(.*) https://sub.domain.com/$1 permanent;
}
server {
        listen 80;
        server_name sub.domain.com;
        rewrite ^/(.*) https://sub.domain.com/$1 permanent;
}
server {
        listen 443;
        ssl    on;
        ssl_certificate    /etc/ssl/certs/myssl.crt;
        ssl_certificate_key     /etc/ssl/private/myssl.key;
        server_name www.sub.domain.com;
        rewrite ^/(.*) http://sub.domain.com/$1 permanent;
}
server {
        listen 443;
        ssl    on;
        ssl_certificate    /etc/ssl/certs/myssl.crt;
        ssl_certificate_key     /etc/ssl/private/myssl.key;
        server_name sub.domain.com;
        access_log /home/wickeduser/public_html/sub.domain.com/log/access.log;
        error_log /home/wickeduser/public_html/sub.domain.com/log/error.log;
        error_page    502 503 504    /error/50x.html;
        location    /error/50x.html {
                internal;
        }
        location / {
                auth_basic "Restricted";
                auth_basic_user_file /etc/sites/htpasswd/sub.domain.com;
                proxy_pass http://localhost:5984;
                proxy_redirect off;
                proxy_set_header Host $host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
}