Mark
#1
Apache CouchDB is a powerful NoSQL database known for its simplicity, ease of replication, and ability to sync across devices. It stores data in JSON format, supports RESTful HTTP APIs, and is perfect for lightweight or distributed applications.
Want to try CouchDB without installing it directly on your system? The easiest way is to run it using Docker. In this guide, you’ll learn how to install and run CouchDB using Docker in just a few minutes.

Why Use Docker to Run CouchDB?

Using Docker for CouchDB gives you a lot of benefits:
  • No need to install CouchDB manually
  • Easy to spin up and remove
  • Runs in an isolated container (no system conflicts)
  • Great for development, testing, or sandbox use
  • Works on Windows, macOS, and Linux

Prerequisites

Before you start, make sure you have Docker installed.

For macOS or Windows:

Download Docker Desktop from:
👉 https://www.docker.com/products/docker-desktop

For Ubuntu/Linux:

sudo apt update && sudo apt install docker.io
Check Docker is installed: 
docker --version

Step 1: Pull the CouchDB Docker Image

First, open your terminal or command prompt and pull the official CouchDB image from Docker Hub: 
docker pull couchdb
You can also specify a version if needed, for example: 
docker pull couchdb:3.3
Using latest is fine for most development setups.

Step 2: Run the CouchDB Container

Now let’s run CouchDB in a Docker container: 
docker run -d --name couchdb \
  -e COUCHDB_USER=admin \
  -e COUCHDB_PASSWORD=secret123 \
  -p 5984:5984 \
  couchdb

What the command does:

  • -d: runs in the background
  • --name couchdb: names the container
  • -e COUCHDB_USER: sets the admin username
  • -e COUCHDB_PASSWORD: sets the admin password
  • -p 5984:5984: maps CouchDB’s HTTP port to your system
  • couchdb: the image you pulled earlier

Step 3: Access CouchDB in Your Browser

Once the container is running, open your browser and go to: 
http://localhost:5984/_utils/
This opens Fauxton, CouchDB’s web-based UI.
Log in with:
  • Username: admin
  • Password: secret123
You can now create databases, documents, and manage CouchDB directly from your browser.

Step 4: Persist Data Using Docker Volumes (Optional)

By default, data inside Docker containers is temporary. If you want to keep your CouchDB data between container restarts, use a Docker volume:

1. Create a volume:

docker volume create couchdb-data

2. Run the container with volume attached:

docker run -d --name couchdb \
  -e COUCHDB_USER=admin \
  -e COUCHDB_PASSWORD=secret123 \
  -p 5984:5984 \
  -v couchdb-data:/opt/couchdb/data \
  couchdb
Now your data will stay even if you restart or remove the container.

Step 5: Manage the CouchDB Container

Here are some useful Docker commands:
Action Command
Stop the container docker stop couchdb
Start it again docker start couchdb
View logs docker logs couchdb
Remove the container docker rm -f couchdb
Remove the volume docker volume rm couchdb-data

Step 6: Interact Using the HTTP API

CouchDB can also be used via its RESTful HTTP API. For example:

Check CouchDB status:

curl http://admin:secret123@localhost:5984/

Create a database:

curl -X PUT http://admin:secret123@localhost:5984/mydatabase

Add a document:

curl -X POST http://admin:secret123@localhost:5984/mydatabase \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'
This is great for automation or scripting.

Best Practices

  • Always use strong passwords for the admin user.
  • Use volumes to persist data in dev and test environments.
  • Don’t expose port 5984 in production without security layers.
  • Use Fauxton for easy data browsing and setup.

image quote pre code
Share: