Configure CouchDB for Production: TLS, Auth, and Compaction (2026)

CouchDB can be configured to serve HTTPS traffic directly, bypassing the need for a separate reverse proxy just for TLS termination.

Let’s set up a CouchDB instance to use TLS, enable authentication, and ensure regular compaction runs. This covers the essential security and performance tuning for a production environment.

Here’s a typical local.ini configuration snippet. We’ll break down each section.

[chttpd]
port = 5984
bind_address = 0.0.0.0
require_valid_user = true
authentication_redirect = true
WWW-Authenticate = Basic realm="Restricted"

[ssl]
enable = true
cert_file = /etc/couchdb/server.crt
key_file = /etc/couchdb/server.key
; Optional: if your cert is signed by an intermediate CA
; ca_file = /etc/couchdb/intermediate.crt

[compaction]
; Run compaction jobs for all databases every 24 hours
; This is a reasonable default, adjust based on write load
; Format: "HH:MM"
default_on = true
default_interval = 24h
default_delay = 60s
default_limit = 10

[admins]
admin = your_super_secret_password

TLS Configuration ([ssl])

The [ssl] section handles TLS. enable = true tells CouchDB to start listening on a TLS-enabled port (which is the same port as [chttpd] by default, 5984). cert_file and key_file are critical. These point to your SSL certificate and its private key. For production, these should be generated by a trusted Certificate Authority (CA), not self-signed. The paths shown are common locations, but adjust them to where you’ve placed your certificate files. ca_file is used if your certificate is signed by an intermediate CA. You’d chain your server certificate with the intermediate CA certificate in this file.

To generate a self-signed certificate for testing (NOT for production):

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/couchdb/server.key -out /etc/couchdb/server.crt -subj "/C=US/ST=State/L=City/O=Organization/CN=your.domain.com"

Why it works: By providing these files, CouchDB can now establish encrypted HTTPS connections. Clients will see the certificate, verify its trust (if not self-signed), and encrypt traffic, protecting data in transit.

Authentication ([chttpd], [admins])

The [chttpd] section controls the HTTP daemon, including authentication settings. require_valid_user = true enforces that all requests must be authenticated with a valid username and password. authentication_redirect = true is useful for interactive use; if a user tries to access a protected resource without credentials, they’ll be redirected to a login prompt. WWW-Authenticate = Basic realm="Restricted" tells browsers what authentication scheme to use and provides a realm for the login prompt.

The [admins] section is where you define administrative users. CouchDB uses a simple salted SHA-1 hash for passwords by default, but it’s best practice to use a strong, unique password. admin = your_super_secret_password creates an admin user named admin with the specified password. You can add multiple lines for multiple admin users.

To create an admin user from the command line:

curl -X PUT http://localhost:5984/_users/org.couchdb.user:new_admin \
  -H "Content-Type: application/json" \
  -d '{"type": "user", "name": "new_admin", "roles": [], "password": "a_very_strong_password"}'

Why it works: When require_valid_user is true, CouchDB checks incoming requests against the user database (_users). If credentials are provided (e.g., via Authorization: Basic ... header), it validates them. This prevents unauthorized access to your data.

Compaction ([compaction])

The [compaction] section automates the database compaction process. default_on = true enables the default compaction scheduler. default_interval = 24h sets how often the scheduler checks if compaction is needed for any database. This means CouchDB will look at all databases every 24 hours. default_delay = 60s is the time CouchDB waits between compacting individual databases within a single scheduled run. default_limit = 10 limits the number of databases that will be compacted in a single scheduled run.

To manually trigger compaction for a specific database:

curl -X POST http://localhost:5984/your_database/_compact

Why it works: CouchDB stores documents and their revisions. Over time, this can lead to fragmentation and increased disk space usage. Compaction rewrites databases, removing old document versions and reclaiming space. Automating this prevents disk bloat and can improve read performance.

Applying the Configuration

1. Save the local.ini file in the CouchDB configuration directory (often /opt/couchdb/etc/couchdb/ or /etc/couchdb/).
2. Restart the CouchDB service for the changes to take effect. On systemd-based systems: sudo systemctl restart couchdb.

After restarting, you should be able to access CouchDB via https://your.domain.com:5984 and will be prompted for the admin credentials you set.

The next hurdle you’ll likely encounter is managing user roles and permissions for different applications or users accessing specific databases.