This page provides a comprehensive, real-world CouchDB configuration baseline for current Debian and RHEL releases, with focus on production readiness and security.
Typical locations:
/etc/couchdb/default.ini
/etc/couchdb/local.ini
/etc/couchdb/local.d/*.ini
Typical locations are the same:
/etc/couchdb/default.ini
/etc/couchdb/local.ini
/etc/couchdb/local.d/*.ini
Best Practice: Use local.ini or files in local.d for your overrides. The local.d/ directory allows for modular configuration with separate files for different concerns (security.ini, performance.ini, etc.).
local.ini ConfigurationUse this baseline for a secure, production-ready CouchDB node:
[chttpd]
; Bind to specific interface (private network) or localhost for single node
bind_address = 127.0.0.1
port = 5984
require_valid_user = true
; Increase timeout for large requests
socket_options = [{recbuf, 262144}, {sndbuf, 262144}]
[chttpd_auth]
require_valid_user = true
authentication_db = _users
timeout = 600
auth_cache_size = 500
iterations = 10
[admins]
admin = -pbkdf2-xxx,salt,iterations ; Use hashed passwords, not plain text
[couchdb]
database_dir = /var/lib/couchdb
view_index_dir = /var/lib/couchdb
single_node = true
; Enable compaction daemon
compaction_daemon = true
; Configure compaction settings
checkpoint_after = 5000
delayed_commits = false
[log]
level = info
writer = file
file = /var/log/couchdb/couchdb.log
[cors]
enable_cors = false
; Only enable if browser-based clients require cross-origin access
;origins = *
;credentials = true
;headers = accept, authorization, content-type, origin, last-modified, etag
[httpd]
; Security header
secure_rewrites = true
; Limit request sizes
max_http_request_size = 4294967296 ; 4GB
[daemons]
; Enable compaction daemon
compaction_daemon = {couch_compaction_daemon, start_link, []}
[compactions]
_default = [{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "01:00"}, {to, "06:00"}]
For clustered setups, do not use single_node = true. Configure each node with its own IP and complete cluster setup via the cluster APIs:
[chttpd]
bind_address = 0.0.0.0 ; Listen on all interfaces for cluster communication
port = 5984
require_valid_user = true
[couchdb]
; Remove single_node setting for clusters
; single_node = true ; Comment out or remove for clusters
[cluster]
q = 2 ; Number of shards (typically 2 for small clusters, 4+ for large)
n = 3 ; Replication factor (typically 3 for high availability)
; Ensure n <= number of nodes in cluster
For high-load environments, consider these additional settings:
[chttpd]
; Connection limits
max_connections = 2048
; Thread pool for HTTP requests
httpd_design_handlers = 4
httpd_db_handlers = 8
[couchdb]
; Increase maximum document size (default is 4GB)
max_document_size = 4294967296
; Memory settings for view processing
os_process_timeout = 10000
[query_server_config]
; Maximum number of processes for query servers
reduce_limit = true
; Timeout for query processes
os_process_soft_limit = 100
[compaction_daemon]
; Interval for checking if compaction is needed
check_interval = 300 ; 5 minutes
; Minimum wait time between compactions of the same database
min_file_size = 131072 ; 128KB
bind_address: Restrict CouchDB to private interfaces only; use 127.0.0.1 for single node, 0.0.0.0 for cluster nodesrequire_valid_user: Prevent unauthenticated access to HTTP API[admins]: Required for secure administration; use hashed passwords, rotate credentials regularlydatabase_dir / view_index_dir: Place on persistent, reliable storage with sufficient spacesingle_node: Correct for standalone deployments, not for multi-node clustersenable_cors: Keep disabled unless browser-based cross-origin clients require itcompaction_daemon: Enables automatic compaction to reclaim disk spacecheckpoint_after: Number of changes after which to checkpoint transaction log5984 private and firewall-restricted_users databaseRestart CouchDB after config changes:
sudo systemctl restart couchdb
# Or reload configuration without restart (some changes require restart)
curl -X POST http://admin:password@127.0.0.1:5984/_node/_local/_config -H "Content-Type: application/json" -d '{"section": "key", "value": "new_value"}'
Validate health and authentication:
curl -s http://127.0.0.1:5984/
curl -s -u admin:your_password http://127.0.0.1:5984/_up
curl -s -u admin:your_password http://127.0.0.1:5984/_membership
Validate admin setup and database access:
curl -s -u admin:your_password http://127.0.0.1:5984/_all_dbs
curl -s -u admin:your_password http://127.0.0.1:5984/_active_tasks
Monitor these key metrics for operational health:
# Check active tasks
curl -s -u admin:your_password http://127.0.0.1:5984/_active_tasks
# Check cluster membership (for clustered setups)
curl -s -u admin:your_password http://127.0.0.1:5984/_membership
# Check statistics
curl -s -u admin:your_password http://127.0.0.1:5984/_stats