CouchDB - Installation

CouchDB - Modern Installation

This chapter guides you through installing CouchDB using modern, recommended methods. The outdated approach of building from source is complex and rarely needed for development or standard production setups. We will focus on Docker for cross-platform development and official package managers for production servers.

Important Note: CouchDB 3.x is secure by default. During setup, you MUST create an administrator user. All examples will use admin as the username and password as the password. Remember to use a strong, secure password in real-world applications.

Method 1: Docker (Recommended for Development)

Docker provides a sandboxed, consistent, and easy-to-manage environment for running CouchDB on any operating system (Windows, macOS, or Linux). It is the ideal choice for local development.

First, ensure you have Docker installed and running on your system.

To start a single-node CouchDB container, run the following command in your terminal:

docker run -d --name my-couchdb -p 5984:5984 -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=password apache/couchdb:3

Let’s break down this command:

• docker run: The command to create and start a new container.
• -d: Runs the container in detached mode (in the background).
• --name my-couchdb: Assigns a memorable name to your container.
• -p 5984:5984: Maps port 5984 on your local machine to port 5984 inside the container. This is how you access CouchDB.
• -e COUCHDB_USER=admin: Sets the admin username via an environment variable.
• -e COUCHDB_PASSWORD=password: Sets the admin password. Use a secure password!
• apache/couchdb:3: Specifies the official CouchDB image, using the latest version 3.x.

CouchDB is now running! That’s all it takes.

Method 2: Official Package Managers (For Linux Servers)

For production Linux servers, it’s best to use the official repositories provided by the Apache CouchDB project to ensure you get timely updates.

For Debian/Ubuntu

# Add the CouchDB repository GPG key
sudo apt-get update && sudo apt-get install -y curl apt-transport-https gnupg
curl -sSL https://apache.jfrog.io/artifactory/couchdb-deb/pubkey.asc | sudo gpg --dearmor -o /usr/share/keyrings/couchdb-archive-keyring.gpg

# Add the repository source
echo "deb [signed-by=/usr/share/keyrings/couchdb-archive-keyring.gpg] https://apache.jfrog.io/artifactory/couchdb-deb/ `lsb_release -cs` main" \
| sudo tee /etc/apt/sources.list.d/couchdb.list >/dev/null

# Install CouchDB
sudo apt-get update
sudo apt-get install -y couchdb

The installer will prompt you to configure CouchDB, including setting up the admin user and password. Choose the ‘standalone’ option for a single-node setup.

For RHEL/CentOS

# Add the CouchDB repository configuration
sudo tee /etc/yum.repos.d/couchdb.repo <<'EOF'
[couchdb]
name=couchdb
baseurl=https://apache.jfrog.io/artifactory/couchdb-rpm/el$releasever/$basearch/
gpgcheck=1
gpgkey=https://apache.jfrog.io/artifactory/couchdb-rpm/pubkey.asc
enabled=1
EOF

# Install CouchDB
sudo yum install -y couchdb

# Start CouchDB (after setting admin credentials in /opt/couchdb/etc/local.ini)
sudo systemctl start couchdb
sudo systemctl enable couchdb

Verification

Once CouchDB is installed and running, you can verify it in two ways:

1. Via cURL

Open a terminal and send an authenticated request to the server’s root endpoint:

$ curl http://admin:password@127.0.0.1:5984/

A successful response will look similar to this (UUID and version may vary):

{
    "couchdb": "Welcome",
    "version": "3.2.1",
    "git_sha": "244d422af",
    "uuid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "features": [
        "access-ready",
        "partitioned",
        "pluggable-storage-engines",
        "reshard",
        "scheduler"
    ],
    "vendor": {
        "name": "The Apache Software Foundation"
    }
}

2. Via Fauxton (The Web UI)

Fauxton is the modern graphical interface for CouchDB, replacing the old ‘Futon’. Open your web browser and navigate to:

http://127.0.0.1:5984/_utils/

You will be greeted by a login screen. Enter the admin credentials you configured (admin and password in our example). Once logged in, you will see the Fauxton dashboard, which allows you to manage databases, documents, and server configuration visually.