Provide mechanism for hosting in subdirs behind reverse proxies

[Joan Touzet]

Comes from: apache/couchdb#2035 and apache/couchdb-documentation#413.

Multiple users have complained that they cannot install CouchDB behind a reverse proxy that is not hosting CouchDB at the top-level / without Fauxton breaking.

@adrienverge provided this comprehensive analysis:

---

Hi @wohali,

I just tried to access Fauxton at http://localhost:8080/db/_utils/, with CouchDB behind a nginx reverse proxy at /db/, and I get the same result as in apache/couchdb#2035: Fauxton loads correctly, databases are listed, but opening one fails with Unexpected token < in JSON at position 0. By looking at the network tab in my browser, it seems that failure comes from an erroneous access to http://localhost:8080/test instead of http://localhost:8080/db/test:

I would say it's a bug or limitation of Fauxton, not a configuration problem, because:

• Fauxton successfully loads _all_dbs, databases infos, and _all_docs inside databases: it is able to use the reverse-proxied URL without any extra conf.
• I briefly looked into Fauxton code and did not find any configuration option to pass a sub-URL.

So in my opinion, it's not documentation to improve here, but a problem to fix in https://github.com/apache/couchdb-fauxton.

[Antonio Maranhao]

This was fixed in #1191

[Joan Touzet]

@Antonio-Maranhao Thank you, but it still appears that when CouchDB with Fauxton in it is running behind a reverse proxy, there are still issues.

Is it this line:

            rewrite /fauxton-dev(.*) /$1 break;

that is required in the NGINX config ahead of CouchDB?

[Antonio Maranhao]

@wohali from the ticket they're using couchdb 2.3.1 but the fix was merged after the Fauxton 1.1.20 release, which explains why they still see the issue.

[skruse]

How would one upgrade fauxton when using the DEB convenience package?

Via npm?

[Joan Touzet]

@skruse There may be other ways, but this should work.

Install Node.JS 8 or later, and git, then follow these steps:

$ mkdir -p couchdb/src couchdb/share
$ git clone https://github.com/apache/couchdb-fauxton couchdb/src/fauxton
$ cd couchdb/src/fauxton
$ npm install --production
$ ./node_modules/grunt-cli/bin/grunt couchdb
$ cd ../../..
$ sudo rm -rf /opt/couchdb/share/dashboard.assets
$ sudo cp -R share/www/* /opt/couchdb/share/www

Be sure you understand what this script is doing before you blindly cut and paste it.

Or wait for us to release 2.4 / 3.0, which will happen in the next 3 months, probably sooner.

[Joan Touzet]

Workaround provided, fix will be in the next release; closing.

[Adam Lacoste]

What is the current ETA for the Fauxton/CouchDB release that will include this fix?

[Willie Möller]

The method that worked for me was to let nginx proxy the /couchdb/_utils/ location to the npm version of fauxton running inside a docker container. All requests to _utils are thus not satisfied by the built-in couchdb fauxton, but instead by the standalone fauxton server.

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. #1199
2. #944
3. #1188

[Pascal]

!Use with caution!

The following fix handles this problem: Fix db url in fetchDatabaseInfo()

If you want to be bold, then you can add the change manually. Go and replace the following part in your bundle.xxx.js in folder /opt/couchdb/share/www

var t=r.default.urls("databaseBaseUrl","server",e),n=u.default.getServerUrl(t);
with
n=r.default.urls("databaseBaseUrl","server",e);

[Cerem Cem ASLAN]

@wohali Thanks for the script you provided. However there were a few typo-like errors. Here is the fixed version:

$ mkdir -p couchdb/src couchdb/share
$ git clone https://github.com/apache/couchdb-fauxton couchdb/src/fauxton
$ cd couchdb/src/fauxton
$ npm install --production
$ ./node_modules/grunt-cli/bin/grunt couchdb
$ cd ../..
$ sudo rm -rf /opt/couchdb/share/www/dashboard.assets
$ sudo cp -R share/www/* /opt/couchdb/share/www

[Ian Cherrill]

!Use with caution!

The following fix handles this problem: Fix db url in fetchDatabaseInfo()

If you want to be bold, then you can add the change manually. Go and replace the following part in your bundle.xxx.js in folder /opt/couchdb/share/www

var t=r.default.urls("databaseBaseUrl","server",e),n=u.default.getServerUrl(t);
with
n=r.default.urls("databaseBaseUrl","server",e);

pas - I tried this but Fauxton just broke in a different way. After looking at Antonio-Maranhao's #1191 fix I guessed that where you put "databaseBaseUrl" it should actually say "databaseBaseURL" as the last three characters in the official fix are capital letters. This worked for me and Fauxton is now running happily from a subdirectory behind NGinx. Of course I would rather install the next version of CouchDb with the official fix, but thanks for allowing me to run Fauxton like this in the meantime.