CouchDB TLS Tutorial

Set up CouchDB using self-signed, locally issued certificates and test that it accepts TLS connections, enforces authentication, and allows secure read/write operations from a test client.

For production purposes, we recommend using publicly trusted certificates issued by a Certificate Authority (CA).

Components

CouchDB image built by Minimus: CouchDB listens only on HTTPS (5984); HTTP is disabled.
Dynamic certificate generation via OpenSSL:
- certgen.sh script: Shell script that generates a custom CA, server, and client certificates using OpenSSL.
- minidebug image: A Minimus dev toolkit that provides a shell, OpenSSL, and other utilities used to generate the certificates.

The test does not persist any certificates on the host machine.

What this guide demonstrates

TLS handshake validation
Server/client certificate trust
Basic auth and CouchDB operations

Directory structure

.
├── certgen.sh              # Script to generate CA, server, and client certs
├── create-certs.yml        # Compose file to generate certs in a dedicated container
├── couchdb-local.ini       # CouchDB configuration with SSL and authentication
└── docker-compose.yml      # Compose file for CouchDB and test client

Deploy CouchDB with self-signed TLS certificates

Step 1: Generate TLS certificates

Save script that generates TLS certificates

Save the following script to a file named certgen.sh. The script is used to generate the TLS certificates and store them in a certs folder on the host.

certgen.sh

#!/bin/sh
# Company: Minimus

set -e
cd /certs

echo "[INFO] Generating OpenSSL config..."
cat > openssl.cnf <<EOF
[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no

[req_distinguished_name]
CN = couchdb

[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = couchdb
DNS.2 = localhost
IP.1 = 127.0.0.1
IP.2 = 192.168.80.0
IP.3 = 192.168.80.2
IP.4 = 192.168.80.3


[v3_ca]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, CA:true
keyUsage = critical, keyCertSign, cRLSign
EOF

echo "[INFO] Creating CA cert..."
openssl genrsa -out ca-key.pem 2048
openssl req -x509 -new -nodes -key ca-key.pem -sha256 -days 365 \
  -out ca.pem -subj "/CN=CouchDB Test CA" \
  -extensions v3_ca -config openssl.cnf

echo "[INFO] Creating server cert..."
openssl genrsa -out server-key.pem 2048
openssl req -new -key server-key.pem -out server.csr \
  -config openssl.cnf -extensions v3_req
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
  -out server-cert.pem -days 365 -sha256 \
  -extfile openssl.cnf -extensions v3_req
cat server-cert.pem ca.pem > server.pem

echo "[INFO] Creating client cert..."
openssl genrsa -out client-key.pem 2048
openssl req -new -key client-key.pem -out client.csr -subj "/CN=couchdb-client"
openssl x509 -req -in client.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
  -out client-cert.pem -days 365 -sha256 \
  -extfile openssl.cnf -extensions v3_req
cat client-cert.pem client-key.pem > client.pem
cat server-cert.pem ca.pem > server.pem

echo "[INFO] Setting file ownership and permissions..."
chown 1000:1000 /certs/*.pem || echo "[WARN] chown failed"
chmod 600 /certs/*-key.pem
chmod 644 /certs/*.pem

echo "[SUCCESS] Certificates successfully created for CouchDB."

Save Docker Compose configuration

Save the following YAML configuration to a file named create-certs.yml. The configuration uses the Minimus minidebug image to generate the certificates with the certgen.sh shell script. Minidebug is a secure Minimus dev toolkit that provides a shell, OpenSSL, and other utilities.The certificates will be persisted in the certs volume on the host.

create-certs.yml

services:
  certgen:
    image: reg.mini.dev/minidebug:latest
    container_name: certgen
    volumes:
    - ./certs:/certs
    - ./certgen.sh:/certgen.sh:ro
    entrypoint:
    - /bin/sh
    - /certgen.sh
    network_mode: none

Generate certificates

Run the following to generate the certificates:

docker compose -f create-certs.yml up

 ✔ Image reg.mini.dev/minidebug:latest Pulled                                                           10.2s
   ✔ *********                         Pull complete                                                     7.9s
 ✔ Container certgen                   Created                                                           0.9s
Attaching to certgen
certgen  | [INFO] Generating OpenSSL config...
certgen  | [INFO] Creating CA cert...
certgen  | [INFO] Creating server cert...
certgen  | Certificate request self-signature ok
certgen  | subject=CN=couchdb
certgen  | [INFO] Creating client cert...
certgen  | Certificate request self-signature ok
certgen  | subject=CN=couchdb-client
certgen  | [INFO] Setting file ownership and permissions...
certgen  | [SUCCESS] Certificates successfully created for CouchDB.

Congrats! You have just generated the following self-signed certificates:

CA certificate (ca.pem)
Server certificates (server-cert.pem, server-key.pem)
Client certificates (client.pem, client-key.pem)

In the next steps, you will mount these certificates into the CouchDB container and configure them via local.ini.

Step 2: Deploy CouchDB server

Save couchdb-local.ini

Save the following configuration to a file named couchdb-local.ini:

couchdb-local.ini

[couchdb] 
single_node = true

[cluster]
n = 1
q = 8

[chttpd_auth_lockout]
mode = off

[chttpd]
; Disable plain HTTP completely by setting an invalid port
port = 0
bind_address = 0.0.0.0
require_valid_user = true

[daemons]
; Enable only HTTPS daemon
httpsd = {couch_httpd, start_link, ["https"]}
; Optionally comment out httpd if not used:
; httpd = {couch_httpd, start_link, ["http"]}

[ssl]
; Now safe to bind to 5984 since HTTP is disabled
port = 5984
enable = true
cert_file = /certs/server-cert.pem
key_file = /certs/server-key.pem
cacert_file = /certs/ca.pem
verify_ssl_certificates = true
verify_ssl_peer = true
fail_if_no_peer_cert = false

[admins]
admin = admin

[authentication]
authentication_handlers = {chttpd_auth, proxy_authentication_handler}, {chttpd_auth, default_authentication_handler}

# Use TLS 1.2+
tls_versions = tlsv1.2,tlsv1.3

Save Docker Compose script

Save the following Docker Compose script to docker-compose.yml. This compose file sets up CouchDB using TLS (HTTPS only), with authentication enabled, mounts the generated certificates, uses the configurations in the local INI file, and exposes CouchDB over https://localhost:15984.

docker-compose.yml

services:
  couchdb:
    image: reg.mini.dev/couchdb:latest-dev
    container_name: couchdb-1
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=admin
      - NODENAME=couchdb
      - COUCHDB_CLUSTER_SIZE=1
    volumes:
      - ./certs:/certs
      - ./data:/opt/couchdb/data
      - ./couchdb-local.ini:/opt/couchdb/etc/local.ini
    ports:
      - "15984:5984"

If you don’t yet have the folder ./data ready and waiting, create it and give it permissions:

mkdir data
sudo chmod -R 777 ./data

Run CouchDB

Start the CouchDB container:

docker compose -f docker-compose.yml up --build -d

Step 3: Test your CouchDB server

Connect to your database and test its connectivity. For example, here are a few commands you can try out:

Check server health:

curl --cacert certs/ca.pem -u admin:admin https://localhost:15984/_up

You should get the response {"seeds":{},"status":"ok"}.

Create and delete a database (for example testdb):

curl --cacert certs/ca.pem \
     -u admin:admin \
     -X PUT \
     https://localhost:15984/testdb

curl --cacert certs/ca.pem \
     -u admin:admin \
     -X DELETE \
     https://localhost:15984/testdb

List all databases:

curl --cacert certs/ca.pem -u admin:admin https://localhost:15984/_all_dbs

["_replicator","_users","testdb"]

You can also pass the request for a JSON format. This option requires the jq JSON processor.

curl --cacert certs/ca.pem -u admin:admin https://localhost:15984/_all_dbs | jq .

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    34    0    34    0     0   1019      0 --:--:-- --:--:-- --:--:--  1030
[
  "_replicator",
  "_users",
  "testdb"
]

Check if a database exists:

curl --cacert certs/ca.pem \
-u admin:admin https://localhost:15984/testdb

{
  "instance_start_time": "1765789065",
  "db_name": "testdb",
  "purge_seq": "0-g1AAAAFDeJzLYWBg4MhgTmHgT84vTc5ISXKA0jlACaY8FiDJ8ABI_QeCrEQGAioPQFTeJ6xyAUTlfsIqGyAq5-NTmZQAJJPqCbgxyQGkKp6QKgWQKnsCqhIZkuQhSrIA1tJnlg",
  "update_seq": "0-g1AAAAJDeJzLYWBg4MhgTmHgT84vTc5ISXKA0jlACaY8FiDJ8ABI_QeCrAzmRIZcoAC7pYWhmaWBBaYuAiYdgJh0H2FSspFxkkmKMckmLYCYtB9hUoqhWWKqmRHJJjVATJqPMCktzcQy1dSUBJOSEoBkUj1KGJkbmVsYWCSRYooDyJR4FFNSLRNNkkxIcosCyBR7FFNSEg1TDC1MSDAlkSFJHsUIs2SL5DQLM0zlWQBKqLC0",
  "sizes": { "file": 66784, "external": 0, "active": 0 },
  "props": {},
  "doc_del_count": 0,
  "doc_count": 0,
  "disk_format_version": 8,
  "compact_running": false,
  "cluster": { "q": 8, "n": 1, "w": 1, "r": 1 }
}

Create document:

curl --cacert certs/ca.pem \
     -u admin:admin \
     -X PUT \
     -H "Content-Type: application/json" \
     -d '{
       "test": "Welcome to TLS couchdb running Minimus image",
       "timestamp": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'"
     }' \
     https://localhost:15984/testdb/doc1

Building Secure Apps

Tutorials

K8s Guides

TLS Guides

Troubleshooting

Debugging

Components

What this guide demonstrates

Directory structure

Deploy CouchDB with self-signed TLS certificates

Step 1: Generate TLS certificates

Step 2: Deploy CouchDB server

Step 3: Test your CouchDB server

​Components

​What this guide demonstrates

​Directory structure

​Deploy CouchDB with self-signed TLS certificates

​Step 1: Generate TLS certificates

​Step 2: Deploy CouchDB server

​Step 3: Test your CouchDB server

Components

What this guide demonstrates

Directory structure

Deploy CouchDB with self-signed TLS certificates

Step 1: Generate TLS certificates

Step 2: Deploy CouchDB server

Step 3: Test your CouchDB server