How to Install CouchDB: Step-by-Step Tutorial

How to Install CouchDB: Complete Step-by-Step Guide

Apache CouchDB is an open-source NoSQL database that focuses on ease of use and having a scalable architecture. This tutorial will guide you through the process of installing CouchDB on popular operating systems with clear steps, prerequisites, troubleshooting tips, and a summary checklist so you can get started quickly.

Prerequisites

A compatible operating system: Linux (Ubuntu/Debian), Windows 10/11, or macOS.
Basic familiarity with command line or terminal usage.
Administrative privileges to install software on your machine.
Internet connection to download installer or packages.

Step 1: Choose Your Installation Method

CouchDB can be installed in multiple ways depending on your platform and preferences:

Linux: Use package managers like apt or yum.
Windows: Use the official CouchDB installer executable.
macOS: Use homebrew or download installers.
Alternatively: Run CouchDB in a Docker container for quick setup.

Step 2: Installing CouchDB on Linux (Ubuntu/Debian)

Open your terminal and follow these commands:

sudo apt update
sudo apt install -y couchdb

During the installation, you will be prompted to configure CouchDB as a standalone or clustered node. For beginners, choose standalone mode.

Once installed, start CouchDB service:

sudo systemctl start couchdb
sudo systemctl enable couchdb

Check that CouchDB is running:

curl http://127.0.0.1:5984/

You should see a JSON response with CouchDB version info.

Step 3: Installing CouchDB on Windows

1. Go to the official Apache CouchDB website and download the latest Windows installer (Official site).

2. Run the downloaded executable and follow the installation prompts.

3. Choose your installation directory and configure basic settings.

4. After installation, CouchDB runs as a Windows service. You can access the admin interface via http://127.0.0.1:5984/_utils/ in your browser.

Step 4: Installing CouchDB on macOS

If you have homebrew installed, open Terminal and run:

brew update
brew install couchdb

This will install CouchDB and its dependencies.

Start CouchDB manually with:

brew services start couchdb

Verify installation by visiting http://127.0.0.1:5984/ in your web browser.

Step 5: Optional – Running CouchDB in Docker

If you prefer containerized environments, use Docker:

docker pull couchdb

docker run -d --name couchdb -p 5984:5984 couchdb

This will start CouchDB in a container accessible on port 5984 of your localhost.

Troubleshooting

Service not starting: Check logs located at /var/log/couchdb/ (Linux) or Event Viewer (Windows).
Port 5984 already in use: Ensure no other services occupy the port or change CouchDB port in the config file local.ini.
Access denied: Verify you have required permissions and firewall rules allow access.
CouchDB web interface not loading: Make sure the database is running, and you are using the correct URL.

Summary Checklist

[ ] Confirm system meets prerequisites.
[ ] Choose appropriate OS installation method.
[ ] Follow installation steps carefully.
[ ] Start and enable CouchDB service.
[ ] Verify installation via browser or curl.
[ ] Troubleshoot common issues if needed.

By following these steps, your CouchDB installation should be up and running, ready to handle your NoSQL database needs. For further learning about database technologies, you might find our how to install Cassandra tutorial helpful to explore other NoSQL databases and broaden your skillset.