4.6. Reverse Proxies

    CouchDB’s sample haproxy configuration is present in the code repository and release tarball as . It is included below. This example is for a 3 node CouchDB cluster:

    Here’s a basic excerpt from an nginx config file in <nginx config directory>/sites-available/default. This will proxy all requests from http://domain.com/... to http://localhost:5984/...

    1. location / {
    2.     proxy_pass http://localhost:5984;
    3.     proxy_redirect off;
    4.     proxy_buffering off;
    5.     proxy_set_header Host $host;
    6.     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    7. }

    Proxy buffering must be disabled, or continuous replication will not function correctly behind nginx.

    4.6.2.2. Reverse proxying CouchDB in a subdirectory with nginx

    It can be useful to provide CouchDB as a subdirectory of your overall domain, especially to avoid CORS concerns. Here’s an excerpt of a basic nginx configuration that proxies the URL http://domain.com/couchdb to http://localhost:5984 so that requests appended to the subdirectory, such as http://domain.com/couchdb/db1/doc1 are proxied to http://localhost:5984/db1/doc1.

    1. location /couchdb {
    2.     rewrite /couchdb/(.*) /$1 break;
    3.     proxy_pass http://localhost:5984;
    4.     proxy_redirect off;
    5.     proxy_buffering off;
    6.     proxy_set_header Host $host;
    7.     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    8. }

    Session based replication is default functionality since CouchDB 2.3.0. To enable session based replication with reverse proxied CouchDB in a subdirectory.

    4.6.2.3. Authentication with nginx as a reverse proxy

    Here’s a sample config setting with basic authentication enabled, placing CouchDB in the /couchdb subdirectory:

    1.     auth_basic "Restricted";
    2.     auth_basic_user_file htpasswd;
    3.     rewrite /couchdb/(.*) /$1 break;
    4.     proxy_pass http://localhost:5984;
    5.     proxy_redirect off;
    6.     proxy_buffering off;
    7.     proxy_set_header Host $host;
    8.     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    9.     proxy_set_header Authorization "";
    10. }

    For a better solution, see .

    In order to enable SSL, just enable the nginx SSL module, and add another proxy header:

    1. ssl on;
    3. ssl_certificate_key PATH_TO_YOUR_PRIVATE_KEY.key;
    4. ssl_protocols SSLv3;
    5. ssl_session_cache shared:SSL:1m;
    7. location / {
    8.     proxy_pass http://localhost:5984;
    9.     proxy_redirect off;
    10.     proxy_set_header Host $host;
    11.     proxy_buffering off;
    12.     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    13.     proxy_set_header X-Forwarded-Ssl on;
    14. }

    The X-Forwarded-Ssl header tells CouchDB that it should use the https scheme instead of the http scheme. Otherwise, all CouchDB-generated redirects will fail.

    Caddy is https-by-default, and will automatically acquire, install, activate and, when necessary, renew a trusted SSL certificate for you - all in the background. Certificates are issued by the Let’s Encrypt certificate authority.

    4.6.3.1. Basic configuration

    Here’s a basic excerpt from a Caddyfile in /etc/caddy/Caddyfile. This will proxy all requests from http(s)://domain.com/... to http://localhost:5984/...

    4.6.3.2. Reverse proxying CouchDB in a subdirectory with Caddy 2

    It can be useful to provide CouchDB as a subdirectory of your overall domain, especially to avoid CORS concerns. Here’s an excerpt of a basic Caddy configuration that proxies the URL http(s)://domain.com/couchdb to http://localhost:5984 so that requests appended to the subdirectory, such as http(s)://domain.com/couchdb/db1/doc1 are proxied to http://localhost:5984/db1/doc1.

    1. domain.com {
    3.     reverse_proxy /couchdb/* localhost:5984

    Caddy will check the status, i.e. health, of each node every 5 seconds; if a node goes down, Caddy will avoid proxying requests to that node until it comes back online.

    1. domain.com {
    4.     lb_policy round_robin
    5.     lb_try_interval 500ms
    7.     health_interval 5s
    8.     }
    10. }

    4.6.3.4. Authentication with Caddy 2 as a reverse proxy

    Here’s a sample config setting with basic authentication enabled, placing CouchDB in the /couchdb subdirectory:

    This setup leans entirely on nginx performing authorization, and forwarding requests to CouchDB with no authentication (with CouchDB in Admin Party mode), which isn’t sufficient in CouchDB 3.0 anymore as Admin Party has been removed. You’d need to at the very least hard-code user credentials into this version with headers.

    For a better solution, see .

    Warning

    As of this writing, there is no way to fully disable the buffering between Apache HTTPD Server and CouchDB. This may present problems with continuous replication. The Apache CouchDB team strongly recommend the use of an alternative reverse proxy such as haproxy or nginx, as described earlier in this section.

    4.6.4.1. Basic Configuration

    1. <VirtualHost *:80>
    2.    ServerAdmin webmaster@dummy-host.example.com
    3.    DocumentRoot "/opt/websites/web/www/dummy"
    4.    ServerName couchdb.localhost
    5.    AllowEncodedSlashes On
    6.    ProxyRequests Off
    7.    KeepAlive Off
    8.    <Proxy *>
    9.       Order deny,allow
    10.       Deny from all
    11.       Allow from 127.0.0.1
    12.    </Proxy>
    13.    ProxyPass / http://localhost:5984 nocanon
    14.    ProxyPassReverse / http://localhost:5984
    15.    ProxyPreserveHost On
    16.    ErrorLog "logs/couchdb.localhost-error_log"
    17.    CustomLog "logs/couchdb.localhost-access_log" common