How to host CouchDB with Fauxton at a non-root location using Nginx as reverse proxy

CouchDB is bundled with a version of Fauxton that has a critical bug that prevents Fauxton from working if CouchDB is hosted at a non-root location. So if you want to host CouchDB at /couchdb, then the bundled Fauxton at /couchdb/_utils would try to access CouchDB at the root location / instead of the location /couchdb, causing Fauxton functionality to break.

The problem is explained in more detail by the following issues on GitHub:

1. https://github.com/apache/couchdb-fauxton/issues/1199
2. https://github.com/apache/couchdb-fauxton/issues/944
3. https://github.com/apache/couchdb-fauxton/issues/1188

Is it possible to host CouchDB with Fauxton at a non-root location using Nginx as a reverse proxy, and how can it be achieved?

I've been using Fauxton behind Nginx at a subfolder location with the following configuration:

    location ^~ /mycouch/ {
        proxy_pass http://192.168.2.5:5984/;
        proxy_redirect off;
        proxy_buffering off;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

A few points to take note:

1. It's proxy_pass http://...5984/;. Notice the / at the end.
2. You should type http://example.com/mycouch/_utils/. Notice the / at the end.
3. There is a problem with Fauxton itself (Unexpected token < in JSON at position 0 error), follow this recipe to build and install the latest version of Fauxton.

The method that worked for me was to let Nginx proxy the /couchdb/_utils/ location to the standalone NPM version of Fauxton running inside a Docker container. All requests to /_utils are thus not satisfied by the bundled CouchDB Fauxton, but instead by the standalone Fauxton server (that has the relevant fixes for subpath hosting).

Here are some hints for the steps required to make this work.

The NGINX configuration at /etc/nginx/conf.d/default.conf:

upstream couchdb {
  server app-couchdb:5984;
}
upstream fauxton {
  server app-fauxton:8000;
}

server {
  listen 80;
  server_name localhost;

  location /couchdb/_utils/ {
    rewrite /couchdb/_utils/(.*) /$1 break;
    proxy_pass http://fauxton/;
    proxy_redirect off;
    proxy_buffering off;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }

  location /couchdb {
    rewrite /couchdb/(.*) /$1 break;
    proxy_pass http://couchdb/;
    proxy_redirect off;
    proxy_buffering off;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
  ...
}

The CouchDB configuration at /opt/couchdb/etc/local.d/docker-1.ini:

[chttpd]
bind_address = 0.0.0.0

[httpd]
enable_cors = true
bind_address = 0.0.0.0

The Dockerfile for the fauxton:alpine image at fauxton.dockerfile:

FROM node:10-alpine
RUN npm install --silent -g fauxton

The docker configuration:

sudo docker build -t fauxton:alpine - < ./fauxton.dockerfile
sudo docker network create app-net
sudo docker create --name app-couchdb --network app-net --restart unless-stopped -v /opt/couchdb/etc/local.d/docker-1.ini:/opt/couchdb/etc/local.d/docker-1.ini -e COUCHDB_USER="$ADMIN_USER" -e COUCHDB_PASSWORD="$ADMIN_PASSWORD" couchdb:latest
sudo docker create --name app-fauxton --network app-net --restart unless-stopped fauxton:alpine fauxton --couchdb "http://app-couchdb:5984"
sudo docker create --name app-nginx --network app-net --restart unless-stopped --publish 8080:80 -v /etc/nginx/conf.d/default.conf:/etc/nginx/conf.d/default.conf:ro nginx:alpine
sudo docker start app-couchdb
sudo docker start app-fauxton
sudo docker start app-nginx

That should more or less give you a setup with the latest version of CouchDB and the latest version of standalone Fauxton, all running inside Docker containers, and accessible via a non-root path at http://127.0.0.1:8080/couchdb/_utils/.

This solution will work for people who are having the following issues:

1. https://github.com/apache/couchdb-fauxton/issues/1199
2. https://github.com/apache/couchdb-fauxton/issues/944
3. https://github.com/apache/couchdb-fauxton/issues/1188