Operating System CentOS

How to Install Apache CouchDB on AlmaLinux 9 and Rocky Linux 9

Install CouchDB 3 from the project's RPM repository on the RHEL 9 family, create the required admin account and complete single-node setup.

Apache CouchDB is a document database that stores JSON and exposes everything over an HTTP API. This guide installs the current CouchDB 3 release from the project's own RPM repository on AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9, creates the mandatory admin account and finishes the single-node setup, so that you end with a working database and the Fauxton web interface.

CentOS 7 reached end of life in June 2024. Older tutorials built CouchDB 1.6 and SpiderMonkey from source on it; none of that is needed any more. The CouchDB project publishes binary packages for the RHEL family, and on release 9 they need one extra repository, EPEL, for the JavaScript engine.

Requirements

  • AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9 on x86_64, with a sudo user.
  • Port 5984 free. CouchDB listens on 127.0.0.1:5984 until you change it.
  • A strong password for the admin account. CouchDB 3 refuses to start without one.

Step 1: Add the CouchDB and EPEL repositories

Update the system, then add the Apache CouchDB repository:

sudo dnf update -y
sudo dnf install -y yum-utils
sudo yum-config-manager --add-repo https://couchdb.apache.org/repo/couchdb.repo

CouchDB's RPM for release 9 depends on the SpiderMonkey package mozjs78, which comes from EPEL. Enable the CRB repository and EPEL:

sudo dnf config-manager --set-enabled crb
sudo dnf install -y epel-release

On CentOS Stream 9, also install the companion package:

sudo dnf install -y epel-next-release

Step 2: Install CouchDB

Install the SpiderMonkey dependency first, then CouchDB:

sudo dnf install -y mozjs78
sudo dnf install -y couchdb

The package installs CouchDB under /opt/couchdb. Configuration lives in /opt/couchdb/etc: default.ini holds the shipped defaults and is overwritten by upgrades, while your own settings belong in local.ini or in files under local.d/, which are read last and win.

Do not start the service yet.

Step 3: Create the admin user

If no admin account exists, CouchDB 3 prints an error and exits. Unlike the Debian package, the RPM does not ask for one, so create it by hand. Write the account to its own file and choose your own password in place of the example:

sudo tee /opt/couchdb/etc/local.d/10-admins.ini > /dev/null <<'EOF'
[admins]
admin = change-this-password
EOF

Restrict the file to the CouchDB service account:

sudo chown couchdb:couchdb /opt/couchdb/etc/local.d/10-admins.ini
sudo chmod 640 /opt/couchdb/etc/local.d/10-admins.ini

The password is plain text only until the first start: CouchDB replaces it in the file with a salted PBKDF2 hash.

Step 4: Configure a single node

A new CouchDB server must be set up either as a single node or as part of a cluster. For one server, tell CouchDB to create its system databases (_users, _replicator and _global_changes) by itself at startup:

sudo tee /opt/couchdb/etc/local.d/20-single-node.ini > /dev/null <<'EOF'
[couchdb]
single_node = true
EOF
sudo chown couchdb:couchdb /opt/couchdb/etc/local.d/20-single-node.ini

Step 5: Start CouchDB and verify

sudo systemctl enable --now couchdb
sudo systemctl status couchdb

Ask the server for its welcome document:

curl http://127.0.0.1:5984/

The JSON reply contains "couchdb":"Welcome" and the version number. Now check that the admin login works and the system databases exist. curl prompts for the password:

curl -u admin http://127.0.0.1:5984/_all_dbs

The list should include _users and _replicator. Confirm too that the password in 10-admins.ini has been replaced with a hash:

sudo cat /opt/couchdb/etc/local.d/10-admins.ini

Step 6: Open Fauxton, the web interface

Fauxton is served by CouchDB itself at /_utils/. Because the server only listens on localhost, the simplest and safest way to reach it is an SSH tunnel from your own computer:

ssh -L 5984:127.0.0.1:5984 deploy@203.0.113.1

Then open http://127.0.0.1:5984/_utils/ in your browser and log in as admin. The Verify page (/_utils/index.html#verifyinstall) runs a short series of create, read, update and replicate tests against your installation.

Step 7: Allow remote access (optional)

If applications on other machines need the database, change the listening address. Add this to a new file:

sudo tee /opt/couchdb/etc/local.d/30-bind.ini > /dev/null <<'EOF'
[chttpd]
bind_address = 0.0.0.0
EOF
sudo chown couchdb:couchdb /opt/couchdb/etc/local.d/30-bind.ini
sudo systemctl restart couchdb

Open the port only for the hosts that need it rather than for the whole internet:

sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="198.51.100.20" port port="5984" protocol="tcp" accept'
sudo firewall-cmd --reload

Port 5984 is plain HTTP, so credentials cross the network unencrypted. For access over the public internet, keep CouchDB on localhost and put a reverse proxy with a TLS certificate in front of it.

Maintenance

  • Updates: sudo dnf upgrade couchdb installs new releases from the Apache repository. Files in local.d/ are left alone.
  • Logs: sudo journalctl -u couchdb shows startup errors, including the message about a missing admin account.
  • Configuration changes at runtime: most settings can be changed without a restart through the API, for example curl -u admin -X PUT http://127.0.0.1:5984/_node/_local/_config/uuids/algorithm -d '"random"'. The server returns the previous value.

Frequently asked questions

Can I install CouchDB on RHEL 10 compatible systems?

Yes. The CouchDB installation documentation lists packages for RHEL/CentOS 10 as well, and there the EPEL step is not required: you add the repository and install couchdb. For Debian and Ubuntu the project provides an APT repository; check the documentation's list of supported releases before you pick a distribution version.

Should I create application users as admins?

No. Entries in the [admins] section are server administrators with full control over every database and the configuration. Create ordinary users as documents in the _users database and grant them access per database through its security settings.

How do I move data from an old CouchDB 1.x server?

Use replication. Start the new CouchDB 3 server, then create a replication in Fauxton (or post a document to _replicator) with the old server's database URL as the source and a database on the new server as the target. Replication works over HTTP between versions, so you do not need to copy database files.

When do I need a cluster instead of a single node?

A single node is enough for development and for many production workloads. A cluster of three or more nodes adds redundancy and lets reads and writes continue when one node is down. Clustering requires additional ports between the nodes and its own setup procedure, described in the CouchDB cluster setup documentation.

Share story:

Continue reading other guides on How VPS.