How to Deploy CouchDB – JSON Document Store

CouchDB is an open-source document-oriented database that stores data as JSON documents. It provides a RESTful HTTP API for all database operations, built-in replication, and multi-version concurrency control. CouchDB's schema-free design makes it ideal for log storage where document structures may vary, and its HTTP-based interface simplifies integration with log collection tools.

In this article, you will deploy CouchDB using Docker Compose, configure persistent storage for database files, and set up Traefik as a reverse proxy to securely access your CouchDB instance.

Prerequisites

Before you begin, you need to:

• Have access to an Ubuntu 24.04-based server as a non-root user with sudo privileges.
• Install Docker and Docker Compose.
• Configure a domain A record pointing to your server's IP address (for example, couchdb.example.com).

Set Up the Directory Structure and Environment Variables

In this section, you prepare the required directory structure for CouchDB and define environment variables in a .env file.

1. Create the directory structure for CouchDB.

   CONSOLE

   Copy

   $ mkdir -p ~/couchdb-logging/couchdb-data

   Explain Code

   Powered by Vultr AgentBeta

   This directory stores database files, views, and configuration settings.

2. Navigate into the couchdb-logging directory.

   CONSOLE

   Copy

   $ cd ~/couchdb-logging

   Explain Code

   Powered by Vultr AgentBeta

3. Set proper ownership for the CouchDB data directory. CouchDB runs as the couchdb user (UID 5984) inside the container.

   CONSOLE

   Copy

   $ sudo chown -R 5984:5984 couchdb-data

   Explain Code

   Powered by Vultr AgentBeta

4. Create a .env file.

   CONSOLE

   Copy

   $ nano .env

   Explain Code

   Powered by Vultr AgentBeta

   Add the following variables:

   INI

   Copy

   DOMAIN=couchdb.example.com
   LETSENCRYPT_EMAIL=admin@example.com
   
   COUCHDB_USER=admin
   COUCHDB_PASSWORD=changeme

   Explain Code

   Powered by Vultr AgentBeta

   Replace:

   • couchdb.example.com with your domain.
   • admin@example.com with your email.
   • changeme with a strong password.

   Save and close the file.

Deploy with Docker Compose

In this section, you create and deploy the Docker Compose stack that runs CouchDB behind Traefik. Docker Compose manages both containers, applies the environment variables from your .env file, and automatically configures HTTPS routing through Traefik.

1. Create a new Docker Compose manifest.

   CONSOLE

   Copy

   $ nano docker-compose.yaml

   Explain Code

   Powered by Vultr AgentBeta

2. Add the following content.

   YAML

   Copy

   services:
     traefik:
       image: traefik:v3.6
       container_name: traefik
       command:
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.websecure.address=:443"
         - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
         - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
         - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
         - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
         - "--certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}"
         - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
       ports:
         - "80:80"
         - "443:443"
       volumes:
         - "letsencrypt:/letsencrypt"
         - "/var/run/docker.sock:/var/run/docker.sock:ro"
       restart: unless-stopped
   
     couchdb:
       image: couchdb:latest
       container_name: couchdb
       hostname: couchdb
       expose:
         - "5984"
       volumes:
         - "./couchdb-data:/opt/couchdb/data"
       environment:
         - COUCHDB_USER=${COUCHDB_USER}
         - COUCHDB_PASSWORD=${COUCHDB_PASSWORD}
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.couchdb.rule=Host(`${DOMAIN}`)"
         - "traefik.http.routers.couchdb.entrypoints=websecure"
         - "traefik.http.routers.couchdb.tls.certresolver=letsencrypt"
         - "traefik.http.services.couchdb.loadbalancer.server.port=5984"
       restart: unless-stopped
   
   volumes:
     letsencrypt:

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

   This configuration includes:

   • services: Two containers collaborate to provide the database stack:
     • traefik: Functions as the edge router, obtaining SSL certificates and directing HTTPS traffic to the database.
     • couchdb: Hosts the NoSQL database engine and serves the RESTful API and web interface.
   • image: Pulls official container images from Docker Hub's verified publishers.
   • container_name: Uses descriptive static names for straightforward container operations.
   • command (Traefik): Activates Docker-based service discovery, opens HTTP (80) and HTTPS (443) listeners, redirects all HTTP to HTTPS automatically, and configures Let's Encrypt ACME client with HTTP-01 challenge method.
   • ports (Traefik): Exposes web service ports 80 and 443 to the host system for public access.
   • expose (CouchDB): Opens port 5984 for inter-container communication only, blocking direct external connections.
   • volumes:
     • Bind mount (./couchdb-data) preserves database files and documents across restarts.
     • Named volume letsencrypt maintains SSL certificate storage independently.
     • Read-only Docker socket access (/var/run/docker.sock:ro) enables dynamic container detection.
   • environment (CouchDB): References administrator credentials from the .env file.
   • labels (CouchDB): Configuration annotations instructing Traefik to proxy requests, route by domain name, attach SSL certificates, and specify the backend service port.
   • restart: unless-stopped: Ensures containers resume operation automatically after failures, excluding manual stops.

3. Create and start the services.

   CONSOLE

   Copy

   $ docker compose up -d

   Explain Code

   Powered by Vultr AgentBeta

4. Verify that the services are running.

   CONSOLE

   Copy

   $ docker compose ps

   Explain Code

   Powered by Vultr AgentBeta

   Output:

   NAME      IMAGE            COMMAND                  SERVICE   CREATED          STATUS          PORTS
   couchdb   couchdb:latest   "tini -- /docker-ent…"   couchdb   18 seconds ago   Up 17 seconds   5984/tcp
   traefik   traefik:v3.6     "/entrypoint.sh --pr…"   traefik   18 seconds ago   Up 17 seconds   0.0.0.0:80->80/tcp, [::]:80->80/tcp, 0.0.0.0:443->443/tcp, [::]:443->443/tcp

   Both containers are operational. CouchDB accepts database requests while Traefik manages connections on ports 80 and 443.

5. View the logs of the services.

   CONSOLE

   Copy

   $ docker compose logs

   Explain Code

   Powered by Vultr AgentBeta

   For more information on managing a Docker Compose stack, see the How To Use Docker Compose article.

Access CouchDB

This section shows how to confirm your CouchDB installation by accessing the Fauxton web console and executing fundamental database operations via the RESTful HTTP interface.

1. Open the CouchDB web interface in your browser.

   https://couchdb.example.com/_utils

2. Sign in with the credentials you configured in the .env file:

   • Username: The value you set for COUCHDB_USER (default: admin)
   • Password: The value you set for COUCHDB_PASSWORD

3. The Fauxton interface displays. This web-based administration console allows you to manage databases, documents, and replication settings.

4. Verify CouchDB is responding using the command line.

   CONSOLE

   Copy

   $ curl https://couchdb.example.com

   Explain Code

   Powered by Vultr AgentBeta

   Output:

   {
     "couchdb": "Welcome",
     "version": "3.5.1",
     "git_sha": "44f6a43d8",
     "uuid": "92800b247a331df27afce9ad744a370b",
     "features": [
       "access-ready",
       "partitioned",
       "pluggable-storage-engines",
       "reshard",
       "scheduler"
     ],
     "vendor": {
       "name": "The Apache Software Foundation"
     }
   }

5. Create a test database.

   CONSOLE

   Copy

   $ curl -X PUT https://admin:changeme@couchdb.example.com/logs

   Explain Code

   Powered by Vultr AgentBeta

   Replace admin:changeme with your actual credentials.

   Output:

   {"ok":true}

6. Insert a sample log document.

   CONSOLE

   Copy

   $ curl -X POST https://admin:changeme@couchdb.example.com/logs \
     -H "Content-Type: application/json" \
     -d '{
       "timestamp": "2025-12-01T20:47:23Z",
       "level": "INFO",
       "message": "Application started successfully",
       "service": "web-server"
     }'

   Explain Code

   Powered by Vultr AgentBeta

   Output includes the document ID and revision:

   {"ok":true,"id":"f234689e3359a8a43434713cb20008a5","rev":"1-6a43114e6467b83a73137f1112b9db8e"}

7. Retrieve all documents from the database.

   CONSOLE

   Copy

   $ curl https://admin:changeme@couchdb.example.com/logs/_all_docs

   Explain Code

   Powered by Vultr AgentBeta

   The response confirms your document was stored successfully.

Conclusion

You have successfully deployed CouchDB for log management with HTTPS encryption. The containerized architecture pairs the document database with automated certificate management, ensuring data persistence across service restarts through bind-mounted volumes. Traefik handles SSL termination and request routing while Let's Encrypt provisions trusted certificates. Your CouchDB deployment can now accept JSON log documents via its RESTful interface, support real-time replication across nodes, and enable advanced log analysis through MapReduce queries and the Fauxton web console.