In CouchDB 2.x, the chttpd section refers to the standard, clustered
port. All use of CouchDB, aside from a few specific maintenance tasks as
described in this documentation, should be performed over this port.

Defines the IP address by which the clustered port is available:

[chttpd]bind_address=127.0.0.1

To let CouchDB listen any available IP address, use 0.0.0.0:

[chttpd]bind_address=0.0.0.0

For IPv6 support you need to set ::1 if you want to let CouchDB
listen correctly:

In CouchDB 2.x, the httpd section mostly refers to the node-local port,
on port 5986 by default. This port is used only for maintenance and
administrative tasks. It should not be used for regular CouchDB access,
and for security reasons, should always be bound to localhost
(127.0.0.1) or a private LAN segment only.

Sets the configuration modification whitelist. Only whitelisted values
may be changed via the config API. To allow the
admin to change this value over HTTP, remember to include
{httpd,config_whitelist} itself. Excluding it from the list would
require editing this file to update the whitelist:

The x_forwarded_host header (X-Forwarded-Host by default) is used
to forward the original value of the Host header field in case, for
example, if a reverse proxy is rewriting the “Host” header field to
some internal host name before forward the request to CouchDB:

[httpd]x_forwarded_host=X-Forwarded-Host

This header has higher priority above Host one, if only it exists
in the request.

x_forwarded_proto header (X-Forwarder-Proto by default) is used
for identifying the originating protocol of an HTTP request, since a
reverse proxy may communicate with CouchDB instance using HTTP even if
the request to the reverse proxy is HTTPS:

The x_forwarded_ssl header (X-Forwarded-Ssl by default) tells
CouchDB that it should use the https scheme instead of the http.
Actually, it’s a synonym for X-Forwarded-Proto:https header, but
used by some reverse proxies:

Limit the maximum size of the HTTP request body. This setting applies
to all requests and it doesn’t discriminate between single vs.
multi-document operations. So setting it to 1MB would block a
PUT of a document larger than 1MB, but it might also block a
_bulk_docs update of 1000 1KB documents, or a multipart/related
update of a small document followed by two 512KB attachments. This
setting is intended to be used as a protection against maliciously
large HTTP requests rather than for limiting maximum document sizes.

[httpd]max_http_request_size=4294967296 ; 4 GB

Warning

Before version 2.1.0 couchdb/max_document_size was
implemented effectively as max_http_request_size. That is, it
checked HTTP request bodies instead of document sizes. After the
upgrade, it is advisable to review the usage of these configuration
settings.

HTTPS setup can be tricky, but the configuration in CouchDB was designed to
be as easy as possible. All you need is two files; a certificate and a
private key. If you have an official certificate from a certificate
authority, both should be in your possession already.

If you just want to try this out and don’t want to go through the hassle of
obtaining an official certificate, you can create a self-signed certificate.
Everything will work the same, but clients will get a warning about an insecure
certificate.

You will need the OpenSSL command line tool installed. It probably
already is.

Now start (or restart) CouchDB. You should be able to connect to it
using HTTPS on port 6984:

shell> curl https://127.0.0.1:6984/curl: (60) SSL certificate problem, verify that the CA cert is OK. Details:error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failedMore details here: http://curl.haxx.se/docs/sslcerts.htmlcurl performs SSL certificate verification by default, using a "bundle"of Certificate Authority (CA) public keys (CA certs). If the defaultbundle file isn't adequate, you can specify an alternate fileusing the --cacert option.If this HTTPS server uses a certificate signed by a CA represented inthe bundle, the certificate verification probably failed due to aproblem with the certificate (it might be expired, or the name mightnot match the domain name in the URL).If you'd like to turn off curl's verification of the certificate, usethe -k (or --insecure) option.

Oh no! What happened?! Remember, clients will notify their users that your
certificate is self signed. curl is the client in this case and it
notifies you. Luckily you trust yourself (don’t you?) and you can specify
the -k option as the message reads:

For performance reasons, and for ease of setup, you may still wish to
terminate HTTPS connections at your load balancer / reverse proxy, then use
unencrypted HTTP between it and your CouchDB cluster. This is a recommended
approach.

The path to a file containing PEM encoded CA certificates. The CA
certificates are used to build the server certificate chain, and for
client authentication. Also the CAs are used in the list of acceptable
client CAs passed to the client when a certificate is requested. May be
omitted if there is no need to verify the client and if there are not
any intermediate CAs for the server certificate:

Set to true to terminate the TLS/SSL handshake with a
handshake_failure alert message if the client does not send a
certificate. Only used if verify_ssl_certificates is true. If set
to false it will only fail if the client sends an invalid certificate
(an empty certificate is considered valid):

CORS, or “Cross-Origin Resource Sharing”, allows a resource such as a web
page running JavaScript inside a browser, to make AJAX requests
(XMLHttpRequests) to a different domain, without compromising the security
of either party.

A typical use case is to have a static website hosted on a CDN make
requests to another resource, such as a hosted CouchDB instance. This
avoids needing an intermediary proxy, using JSONP or similar workarounds
to retrieve and host content.

While CouchDB’s integrated HTTP server has support for document attachments
makes this less of a constraint for pure CouchDB projects, there are many
cases where separating the static content from the database access is
desirable, and CORS makes this very straightforward.

By supporting CORS functionality, a CouchDB instance can accept direct
connections to protected databases and instances, without the browser
functionality being blocked due to same-origin constraints. CORS is
supported today on over 90% of recent browsers.

CORS support is provided as experimental functionality in 1.3, and as such
will need to be enabled specifically in CouchDB’s configuration. While all
origins are forbidden from making requests by default, support is available
for simple requests, preflight requests and per-vhost configuration.

By default, neither authentication headers nor cookies are included in
requests and responses. To do so requires both setting
XmlHttpRequest.withCredentials=true on the request object in the
browser and enabling credentials support in CouchDB.

[cors]credentials=true

CouchDB will respond to a credentials-enabled CORS request with an
additional header, Access-Control-Allow-Credentials=true.

CouchDB can map requests to different locations based on the Host
header, even if they arrive on the same inbound IP address.

This allows different virtual hosts on the same machine to map to different
databases or design documents, etc. The most common use case is to map a
virtual host to a Rewrite Handler, to provide
full control over the application’s URIs.

To add a virtual host, add a CNAME pointer to the DNS for your domain
name. For development and testing, it is sufficient to add an entry in the
hosts file, typically /etc/hosts` on Unix-like operating systems:

If your CouchDB is listening on the the default HTTP port (80), or is
sitting behind a proxy, then you don’t need to specify a port number in the
vhost key.

The first line will rewrite the request to display the content of the
example database. This rule works only if the Host header is
couchdb.local and won’t work for CNAMEs. The second rule, on the
other hand, matches all CNAMEs to example db, so that both
www.couchdb.local and db.couchdb.local will work.

If xframe_options is enabled it will return X-Frame-Options: DENY by default.
If same_origin is enabled it will return X-Frame-Options: SAMEORIGIN.
A X-FRAME-OPTIONS: ALLOW-FROM url will be returned when same_origin
is false, and the HOST header matches one of the urls in the hosts config.
Otherwise a X-Frame-Options: DENY will be returned.