Apache CouchDB 3.5.3

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick Apache CouchDB 3.5.3 on Ubuntu 24.04 as the software version, select your Region, and choose Launch through EC2.

Choose m5.large, your key pair and a security group as described in the prerequisites. The AMI includes its own 20 GiB data volume for CouchDB. If you expect more data, increase its size on the launch page (see Step 9).

To launch with the AWS CLI instead, replace the values in angle brackets:

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=couchdb}]'

Version SSH user

Apache CouchDB 3.5.3 on Ubuntu 24.04 ubuntu

ssh -i <your-key.pem> ubuntu@<public-ip>

First boot generates the certificate, the administrator password, the secrets and the Erlang cookie. Then CouchDB and nginx start. Allow about a minute after the instance reaches the running state, then check the services:

systemctl is-active couchdb nginx couchdb-firstboot
sudo test -f /var/lib/sac/data/couchdb-firstboot.done && echo FIRSTBOOT_DONE dpkg-query -W -f '${Package} ${Version}\n' couchdb apt-mark showhold

active active active FIRSTBOOT_DONE couchdb 3.5.3~noble couchdb

Only SSH and nginx listen on public addresses. CouchDB (5984), its Erlang distribution (9100) and epmd (4369) are on loopback:

sudo ss -Hlntp | awk '{print $4, $6}' | grep -v '127.0.0.5' | sed -E 's/,pid=[0-9]+,fd=[0-9]+//g' | sort

0.0.0.0:22 users:(("sshd"),("systemd")) 0.0.0.0:443 users:(("nginx"),("nginx"),("nginx")) 0.0.0.0:80 users:(("nginx"),("nginx"),("nginx")) 127.0.0.1:4369 users:(("epmd")) 127.0.0.1:5984 users:(("beam.smp")) 127.0.0.1:9100 users:(("beam.smp")) [::1]:4369 users:(("epmd")) [::]:22 users:(("sshd"),("systemd")) [::]:443 users:(("nginx"),("nginx"),("nginx")) [::]:80 users:(("nginx"),("nginx"),("nginx"))

The URLs and the administrator user are in the root-only credentials file:

sudo grep -E '^COUCHDB_(URL|FAUXTON_URL|ADMIN_USER)=' /root/couchdb-credentials.txt

COUCHDB_URL=https://ec2-<public-ip-dashed>.compute-1.amazonaws.com/ COUCHDB_FAUXTON_URL=https://ec2-<public-ip-dashed>.compute-1.amazonaws.com/_utils/ COUCHDB_ADMIN_USER=admin

The same file holds COUCHDB_ADMIN_PASSWORD, which is unique to this instance. Read it with sudo grep '^COUCHDB_ADMIN_PASSWORD=' /root/couchdb-credentials.txt and keep it in your password manager. CouchDB itself keeps only a PBKDF2 hash of it.

The URLs use the instance's public DNS name from EC2 instance metadata (IMDSv2). If the instance has no public name, they use its public or private IPv4 address. The certificate names that host plus the instance's public and private IP addresses:

openssl x509 -in /etc/ssl/couchdb/couchdb.crt -noout -subject -ext subjectAltName -enddate

subject=CN = ec2-<public-ip-dashed>.compute-1.amazonaws.com, O = sac X509v3 Subject Alternative Name: DNS:ec2-<public-ip-dashed>.compute-1.amazonaws.com, IP Address:<public-ip>, IP Address:<private-ip>, IP Address:127.0.0.1, DNS:localhost notAfter=<date about 27 months after first boot>

Without a login, every CouchDB request answers 401. A wrong password is refused, and port 80 redirects to HTTPS. The following commands read the password from the credentials file into a shell variable and pass it to curl through a file descriptor, so it never appears in the process list or your shell history:

H=$(sudo sed -n 's#^COUCHDB_URL=https://\([^/]*\)/.*#\1#p' /root/couchdb-credentials.txt)
PW=$(sudo sed -n 's/^COUCHDB_ADMIN_PASSWORD=//p' /root/couchdb-credentials.txt) R=(--cacert /etc/ssl/couchdb/couchdb.crt --resolve "$H:443:127.0.0.1") curl -s -o /dev/null -w 'http:// -> %{http_code} %{redirect_url}\n' --resolve "$H:80:127.0.0.1" "http://$H/" curl -s -o /dev/null -w '/_all_dbs, no login -> HTTP %{http_code}\n' "${R[@]}" "https://$H/_all_dbs" curl -s -o /dev/null -w '/_utils/ (Fauxton), no login -> HTTP %{http_code}\n' "${R[@]}" "https://$H/_utils/" curl -s -o /dev/null -w '/_all_dbs, wrong password -> HTTP %{http_code}\n' "${R[@]}" -K <(printf 'user = "admin:admin"\n') "https://$H/_all_dbs" curl -s -w ' <- /_all_dbs, your password\n' "${R[@]}" -K <(printf 'user = "admin:%s"\n' "$PW") "https://$H/_all_dbs" curl -s "${R[@]}" -K <(printf 'user = "admin:%s"\n' "$PW") "https://$H/" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["couchdb"], d["version"], "|", ", ".join(d["features"]))' curl -s -w ' <- /healthz (no login)\n' "${R[@]}" "https://$H/healthz"

http:// -> 301 https://ec2-<public-ip-dashed>.compute-1.amazonaws.com/ /_all_dbs, no login -> HTTP 401 /_utils/ (Fauxton), no login -> HTTP 401 /_all_dbs, wrong password -> HTTP 401 ["_replicator","_users"] <- /_all_dbs, your password Welcome 3.5.3 | quickjs, access-ready, partitioned, pluggable-storage-engines, reshard, scheduler ok <- /healthz (no login)

--resolve sends the request to this instance while keeping the real host name, so the certificate check passes. From another machine, drop --resolve and use the URL directly, for example curl -u admin https://<your-host>/_all_dbs. curl prompts for the password.

/healthz is a static nginx endpoint for load balancer health checks. CouchDB's own /_up needs a login like every other CouchDB path.

This example creates an inventory database and adds three documents in one _bulk_docs request. It then runs a Mango query (red items in stock), adds a JavaScript map/reduce view that totals stock by type, and queries the view. The helper c sends each request with your password from a file descriptor:

H=$(sudo sed -n 's#^COUCHDB_URL=https://\([^/]*\)/.*#\1#p' /root/couchdb-credentials.txt)
PW=$(sudo sed -n 's/^COUCHDB_ADMIN_PASSWORD=//p' /root/couchdb-credentials.txt) c() { curl -s --cacert /etc/ssl/couchdb/couchdb.crt --resolve "$H:443:127.0.0.1" -K <(printf 'user = "admin:%s"\n' "$PW") -H 'Content-Type: application/json' "$@"; echo; } c -X PUT "https://$H/inventory" c -X POST "https://$H/inventory/_bulk_docs" -d '{"docs":[{"_id":"widget-1","type":"widget","colour":"red","stock":12},{"_id":"widget-2","type":"widget","colour":"blue","stock":0},{"_id":"gadget-1","type":"gadget","colour":"red","stock":5}]}' | sed -E 's/"rev":"[^"]*"/"rev":"1-<rev>"/g' c -X POST "https://$H/inventory/_find" -d '{"selector":{"colour":"red","stock":{"$gt":0}},"fields":["_id","stock"]}' | python3 -c 'import json,sys; print(json.dumps(json.load(sys.stdin)["docs"]))' c -X PUT "https://$H/inventory/_design/stock" -d '{"views":{"by_type":{"map":"function (doc) { emit(doc.type, doc.stock); }","reduce":"_sum"}}}' | sed -E 's/"rev":"[^"]*"/"rev":"1-<rev>"/' c "https://$H/inventory/_design/stock/_view/by_type?group=true"

{"ok":true} [{"ok":true,"id":"widget-1","rev":"1-<rev>"},{"ok":true,"id":"widget-2","rev":"1-<rev>"},{"ok":true,"id":"gadget-1","rev":"1-<rev>"}] [{"_id": "gadget-1", "stock": 5}, {"_id": "widget-1", "stock": 12}] {"ok":true,"id":"_design/stock","rev":"1-<rev>"} {"rows":[ {"key":"gadget","value":5}, {"key":"widget","value":12} ]}

For queries you run often, create a Mango index first (POST /inventory/_index with {"index":{"fields":["colour"]}}).

New databases are readable and writable by server admins only (default_security = admin_only). To give an application its own login, create a user in the _users database and add it to the database's _security members. Applications then never need the admin password.

Open the COUCHDB_FAUXTON_URL from Step 4 (https://<your-host>/_utils/) in a browser. The certificate is self-signed, so the browser warns you once. Accept the warning, or install your own certificate (Step 10). The browser then asks for a user and password. Sign in as admin with COUCHDB_ADMIN_PASSWORD.

Fauxton opens on the Databases page. It lists the system databases _users and _replicator and the databases you created:

Choose a database to browse its documents, run Mango queries, manage its permissions and follow its changes feed:

Choose a document to edit its JSON, upload attachments or clone it:

Open a view under Design Documents to see its results:

The Replication page creates and monitors replication jobs. The Configuration page shows CouchDB's settings, and Log Out ends the session. Fauxton runs entirely in your browser and talks only to your instance.

Replication copies every document and revision from a source database to a target. It can run once or continuously, in either direction, between this instance and any other CouchDB or PouchDB endpoint. Credentials for each side go in an auth object inside the request body, never in a URL or on a command line.

This example makes a one-off copy of inventory on the same server. The shell's own printf builds the body, which is piped to curl:

H=$(sudo sed -n 's#^COUCHDB_URL=https://\([^/]*\)/.*#\1#p' /root/couchdb-credentials.txt)
PW=$(sudo sed -n 's/^COUCHDB_ADMIN_PASSWORD=//p' /root/couchdb-credentials.txt) c() { curl -s --cacert /etc/ssl/couchdb/couchdb.crt --resolve "$H:443:127.0.0.1" -K <(printf 'user = "admin:%s"\n' "$PW") -H 'Content-Type: application/json' "$@"; echo; } printf '{"source":{"url":"http://127.0.0.1:5984/inventory","auth":{"basic":{"username":"admin","password":"%s"}}},"target":{"url":"http://127.0.0.1:5984/inventory-backup","auth":{"basic":{"username":"admin","password":"%s"}}},"create_target":true}' "$PW" "$PW" \
  | c -X POST "https://$H/_replicate" --data-binary @- | python3 -c 'import json,sys; d=json.load(sys.stdin); h=d["history"][0]; print("ok:", d["ok"], "| docs_written:", h["docs_written"], "| doc_write_failures:", h["doc_write_failures"])' c "https://$H/inventory-backup" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["db_name"], "doc_count:", d["doc_count"])'

ok: True | docs_written: 4 | doc_write_failures: 0 inventory-backup doc_count: 4

To replicate with another server, use its HTTPS URL as the source or target, and put that server's credentials in its auth object.

For a replication that survives restarts, create a document in the _replicator database with the same fields, plus "continuous": true to keep it running. You can also use Fauxton's Replication page. Remote servers reach this instance at https://<your-host>/<database> with a user you created for them. The replicator can reach other hosts but never the instance metadata service (Step 8).

CouchDB runs as the unprivileged couchdb user. The following commands show the service settings and probe from inside the CouchDB service. The instance metadata service is unreachable, while CouchDB itself answers on loopback with 401, because every request needs a login:

systemctl show couchdb -p User -p NoNewPrivileges -p ProtectSystem -p ProtectHome -p PrivateTmp -p ReadWritePaths -p IPAddressDeny
systemctl show nginx -p IPAddressDeny
CG=$(systemctl show -p ControlGroup --value couchdb)
sudo bash -c "echo \$\$ > /sys/fs/cgroup$CG/cgroup.procs; curl -s -m 5 -o /dev/null -w 'from inside couchdb: instance metadata -> %{http_code}\n' http://169.254.169.254/latest/meta-data/; curl -s -m 5 -o /dev/null -w 'from inside couchdb: loopback CouchDB -> %{http_code}\n' http://127.0.0.1:5984/_up"

IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128 User=couchdb ReadWritePaths=/var/lib/couchdb /var/log/couchdb /opt/couchdb/etc/local.d PrivateTmp=yes ProtectHome=yes ProtectSystem=strict NoNewPrivileges=yes IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128 from inside couchdb: instance metadata -> 000 from inside couchdb: loopback CouchDB -> 401

CouchDB is an Erlang application and uses its own Erlang distribution layer. Anyone holding the Erlang cookie could use that layer to run code inside CouchDB. On this image, the distribution and epmd listen on loopback only. First boot generates the cookie into /opt/couchdb/.erlang.cookie, which only couchdb can read. The couchdb.service unit reads its VM arguments from /etc/couchdb-sac/vm.args, which carries no cookie, so the cookie never appears in the process list.

The instance's secrets and the administrator hash are in /opt/couchdb/etc/local.d/90-sac-instance.ini, which only CouchDB can read. The hash uses CouchDB's PBKDF2 format:

sudo stat -c '%a %U %n' /opt/couchdb/.erlang.cookie /opt/couchdb/etc/local.d/90-sac-instance.ini /root/couchdb-credentials.txt
sudo grep -c '^-setcookie' /etc/couchdb-sac/vm.args
sudo grep -E '^-kernel inet_dist' /etc/couchdb-sac/vm.args ps -o args= -C beam.smp | tr ' ' '\n' | grep -c -- '-setcookie'
sudo sed -n 's/^\(admin\) = \(-pbkdf2:[a-z0-9]*\)-.*,\([0-9]*\)$/\1 = \2-<derived key>,<salt>,\3/p' /opt/couchdb/etc/local.d/90-sac-instance.ini

400 couchdb /opt/couchdb/.erlang.cookie 600 couchdb /opt/couchdb/etc/local.d/90-sac-instance.ini 600 root /root/couchdb-credentials.txt 0 -kernel inet_dist_use_interface {127,0,0,1} -kernel inet_dist_listen_min 9100 -kernel inet_dist_listen_max 9200 0 admin = -pbkdf2:sha256-<derived key>,<salt>,600000

The SecureAnyCloud settings are in /opt/couchdb/etc/local.d/10-sac.ini:

sudo grep -E '^(require_valid_user|bind_address|js_engine|single_node|admin_only_all_dbs) =' /opt/couchdb/etc/local.d/10-sac.ini

single_node = true js_engine = quickjs bind_address = 127.0.0.1 require_valid_user = true admin_only_all_dbs = true

CouchDB cannot read /etc/shadow, the TLS key, the credentials file or the nginx configuration. Those paths are root-only or hidden from the service.

If an application needs CouchDB to reach a host that the service may not reach, adjust /etc/systemd/system/couchdb.service.d/ deliberately and run sudo systemctl daemon-reload && sudo systemctl restart couchdb. Keep the instance metadata deny in place.

Every database lives under /var/lib/couchdb on the dedicated EBS volume. CouchDB's log is /var/log/couchdb/couchdb.log:

df -h /var/lib/couchdb | tail -1 | awk '{print $2" total, "$4" free on "$6}'
sudo ls /var/lib/couchdb

20G total, 19G free on /var/lib/couchdb _dbs.couch _nodes.couch lost+found shards

• Disk. To grow the volume, modify it in the EC2 console (Volumes, Modify volume), then extend the file system online with sudo resize2fs "$(findmnt -no SOURCE /var/lib/couchdb)".
• Backups. Replicate to another CouchDB (Step 7), or stop CouchDB (sudo systemctl stop couchdb) and take an EBS snapshot of the data volume. Back up /opt/couchdb/etc/local.d/90-sac-instance.ini with it, because it holds the administrator hash and the server UUID. First boot never runs again on an instance that has completed it.
• Configuration. Change settings in Fauxton's Configuration page or through the _node/_local/_config API. CouchDB saves them in 90-sac-instance.ini. You can also edit 10-sac.ini and run sudo systemctl restart couchdb. CouchDB's own defaults are in /opt/couchdb/etc/default.ini. Do not edit that file.
• JavaScript engine. Views and validation functions run in CouchDB's bundled QuickJS engine. If a design document needs the SpiderMonkey engine instead, set js_engine = spidermonkey in 10-sac.ini and restart CouchDB. SpiderMonkey 115 comes from Ubuntu's libmozjs-115-0t64, which Ubuntu does not patch. That is why the image does not use it by default.
• Upgrades. CouchDB is held at 3.5.3 (apt-mark showhold). To move to a newer CouchDB release from Apache's repository, read its release notes, take a snapshot, then run sudo apt-mark unhold couchdb && sudo apt-get update && sudo apt-get install couchdb && sudo apt-mark hold couchdb. SecureAnyCloud's settings live in local.d and /etc/couchdb-sac, which the package does not overwrite.
• Logs. journalctl -u couchdb shows the service output, and journalctl -u couchdb-firstboot shows what first boot did. nginx logs requests to /var/log/nginx/access.log without query strings.

The served host name is fixed by configuration and never taken from a request. To serve CouchDB under your own DNS name, point the name at the instance and run the helper. The helper records the name, regenerates the self-signed certificate for it, updates the credentials file and reloads nginx:

sudo couchdb-set-hostname <your-dns-name>

If the instance's public DNS name changes after a stop and start, run the same command again. An Elastic IP avoids this. The instance drops requests for a name it does not serve.

To use a certificate from your own CA or a public CA instead, replace /etc/ssl/couchdb/couchdb.crt (full chain) and /etc/ssl/couchdb/couchdb.key (mode 0600, owner root), then run sudo nginx -t && sudo systemctl reload nginx.

SSH accepts keys only. Passwords, root logins and X11 forwarding are switched off in /etc/ssh/sshd_config.d/00-sac.conf, which sorts before every other SSH setting. Check the effective values:

sudo sshd -T | grep -E '^(passwordauthentication|kbdinteractiveauthentication|permitrootlogin|x11forwarding|pubkeyauthentication) '

permitrootlogin no pubkeyauthentication yes passwordauthentication no kbdinteractiveauthentication no x11forwarding no

Other points:

• Change the administrator password with CouchDB's configuration API, sending the new password in the request body. CouchDB hashes it and saves only the hash in 90-sac-instance.ini. Then update /root/couchdb-credentials.txt. For example, from a file that only you can read, run curl -s --cacert /etc/ssl/couchdb/couchdb.crt -u admin -X PUT https://<your-host>/_node/_local/_config/admins/admin --data-binary @new-password.json. The file holds the new password as a JSON string.
• A server admin can change any setting and read every database. Give applications their own users in _users and database-level permissions, not the admin password.
• nginx logs the real client address of every request without its query string. It ignores X-Forwarded-For headers sent by clients, and CouchDB's lockout counts failed logins per real address. The AMI requires IMDSv2. Restrict port 443 to the networks that use CouchDB.
• Bundled components. CouchDB 3.5.3 is the newest CouchDB release and fixes every CouchDB security advisory published so far. It bundles Erlang/OTP 27 (ERTS 15.2.7.13) without the Erlang SSH application. Two OTP TLS advisories were published after the CouchDB release: CVE-2026-94200 (the TLS client session ticket store) and CVE-2026-105236 (TLS 1.2 session resumption across SNI host names). Neither applies here, because CouchDB serves no TLS itself (nginx does), and its replicator's TLS client does not enable session tickets. The optional Nouveau search server (Java libraries under /opt/couchdb/nouveau, which a scanner reports with Jackson and Jetty advisories) is switched off and cannot run, because no Java runtime is installed. SecureAnyCloud updates the image when Apache ships a newer CouchDB release.

When you have finished with the example data from Steps 5 and 7, delete it:

H=$(sudo sed -n 's#^COUCHDB_URL=https://\([^/]*\)/.*#\1#p' /root/couchdb-credentials.txt)
PW=$(sudo sed -n 's/^COUCHDB_ADMIN_PASSWORD=//p' /root/couchdb-credentials.txt) for db in inventory inventory-backup; do curl -s -w " <- delete $db\n" --cacert /etc/ssl/couchdb/couchdb.crt --resolve "$H:443:127.0.0.1" -K <(printf 'user = "admin:%s"\n' "$PW") -X DELETE "https://$H/$db"; done

{"ok":true} <- delete inventory {"ok":true} <- delete inventory-backup