10.3. nginx as a Reverse Proxy¶
CouchDB recommends the use of HAProxy as a load balancer and reverse proxy. The team’s experience with using it in production has shown it to be superior for configuration and montioring capabilities, as well as overall performance.
CouchDB’s sample haproxy configuration is present in the code repository and
release tarball as rel/haproxy.cfg
.
However, nginx
is a suitable alternative. Below are instructions on
configuring nginx appropriately.
10.3.1. Basic configuration¶
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/...
location / {
proxy_pass http://localhost:5984;
proxy_redirect off;
proxy_buffering off;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
Proxy buffering must be disabled, or continuous replication will not function correctly behind nginx.
10.3.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
.
location /couchdb {
rewrite /couchdb/(.*) /$1 break;
proxy_pass http://localhost:5984;
proxy_redirect off;
proxy_buffering off;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
Note that in the above configuration, the Verify Installation link in Fauxton may not succeed.
10.3.3. Authentication with nginx as a reverse proxy¶
Here’s a sample config setting with basic authentication enabled, placing
CouchDB in the /couchdb
subdirectory:
location /couchdb {
auth_basic "Restricted";
auth_basic_user_file htpasswd;
rewrite /couchdb/(.*) /$1 break;
proxy_pass http://localhost:5984;
proxy_redirect off;
proxy_buffering off;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Authorization "";
}
This setup leans entirely on nginx performing authorization, and forwarding requests to CouchDB with no authentication (with CouchDB in Admin Party mode). For a better solution, see Proxy Authentication.
10.3.4. SSL with nginx¶
In order to enable SSL, just enable the nginx SSL module, and add another proxy header:
ssl on;
ssl_certificate PATH_TO_YOUR_PUBLIC_KEY.pem;
ssl_certificate_key PATH_TO_YOUR_PRIVATE_KEY.key;
ssl_protocols SSLv3;
ssl_session_cache shared:SSL:1m;
location / {
proxy_pass http://localhost:5984;
proxy_redirect off;
proxy_set_header Host $host;
proxy_buffering off;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Ssl on;
}
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.