How to Install Apache CouchDB on Docker

Introduction

Apache CouchDB is a powerful, open-source NoSQL database that uses JSON for documents, JavaScript for MapReduce indexes, and HTTP for its API. It is designed for ease of use, scalability, and reliability. Docker, on the other hand, is a platform that allows you to containerize applications, making them portable and easy to deploy across different environments.

In this guide, we will walk you through the process of installing Apache CouchDB on Docker. By the end of this article, you will have a fully functional CouchDB instance running inside a Docker container.

Prerequisites

Before we begin, ensure that you have the following prerequisites:

• Docker Installed: Make sure Docker is installed on your system. You can download and install Docker from the official Docker website.
• Basic Knowledge of Docker: Familiarity with Docker concepts such as images, containers, and volumes will be helpful.
• Command Line Access: You should have access to a terminal or command line interface to execute Docker commands.

Step 1: Pull the Official CouchDB Docker Image

The first step is to pull the official Apache CouchDB Docker image from Docker Hub. Docker Hub is a repository of Docker images that you can use to create containers.

docker pull couchdb:latest

This command downloads the latest version of the CouchDB image. If you want a specific version, you can replace latest with the version number, e.g., couchdb:3.1.1.

Step 2: Run the CouchDB Container

Once the image is downloaded, you can run a CouchDB container using the following command:

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

Let’s break down this command:

• -d: Runs the container in detached mode (in the background).
• --name my-couchdb: Assigns a name to the container for easier management.
• -p 5984:5984: Maps port 5984 on your local machine to port 5984 in the container. CouchDB uses this port for HTTP communication.
• couchdb:latest: Specifies the Docker image to use.

After running this command, CouchDB will be up and running inside the Docker container.

Step 3: Verify the Installation

To verify that CouchDB is running correctly, you can access the CouchDB web interface or use a command-line tool like curl.

Option 1: Access the Web Interface

Open your web browser and navigate to http://localhost:5984/_utils. You should see the CouchDB web interface, also known as Fauxton. This interface allows you to manage databases, documents, and more.

Option 2: Use Curl

You can also use the curl command to check if CouchDB is running:

curl http://localhost:5984

If CouchDB is running, you should see a JSON response similar to the following:

{
  "couchdb": "Welcome",
  "version": "3.1.1",
  "git_sha": "some-git-sha",
  "uuid": "some-uuid",
  "features": ["pluggable-storage-engines", "scheduler"],
  "vendor": {
    "name": "The Apache Software Foundation"
  }
}

Step 4: Configure CouchDB (Optional)

By default, CouchDB runs in “admin party” mode, which means anyone can access it without authentication. For production environments, you should secure your CouchDB instance by creating an admin user.

Create an Admin User

To create an admin user, you need to access the CouchDB container’s shell and run the following commands:

docker exec -it my-couchdb bash

This command opens a bash shell inside the running CouchDB container. Once inside, run the following command to create an admin user:

curl -X PUT http://localhost:5984/_node/_local/_config/admins/admin -d '"password"'

Replace admin with your desired username and password with your desired password. After running this command, CouchDB will require authentication for all requests.

Step 5: Persist Data Using Docker Volumes

By default, data stored in a Docker container is ephemeral, meaning it will be lost when the container is removed. To persist CouchDB data, you can use Docker volumes.

Create a Docker Volume

First, create a Docker volume to store CouchDB data:

docker volume create couchdb-data

Run CouchDB with the Volume

Next, run the CouchDB container with the volume mounted:

docker run -d --name my-couchdb -p 5984:5984 -v couchdb-data:/opt/couchdb/data couchdb:latest

This command mounts the couchdb-data volume to the /opt/couchdb/data directory inside the container, where CouchDB stores its data.

Step 6: Manage the CouchDB Container

Here are some useful Docker commands for managing your CouchDB container:

• Stop the Container: docker stop my-couchdb
• Start the Container: docker start my-couchdb
• Remove the Container: docker rm my-couchdb
• View Logs: docker logs my-couchdb

Conclusion

In this guide, we covered how to install Apache CouchDB on Docker, from pulling the Docker image to running and managing the container. We also discussed how to secure your CouchDB instance and persist data using Docker volumes.

By following these steps, you can easily set up a CouchDB instance in a Docker container, making it portable and easy to deploy across different environments. Whether you’re developing locally or deploying to production, Docker provides a convenient way to manage your CouchDB instances.