docker.recipes

CouchDB Cluster

beginner

Apache CouchDB document database with Fauxton UI.

Overview

Apache CouchDB is a document-oriented NoSQL database that pioneered the concept of multi-master replication and offline-first data synchronization. Originally developed by Damien Katz at Lotus Notes and later open-sourced through the Apache Software Foundation, CouchDB uses a schema-free JSON document model with a RESTful HTTP API, making it uniquely suited for distributed applications that need reliable data sync across multiple nodes or devices. Unlike traditional databases that require complex master-slave configurations, CouchDB treats all nodes as equals in a cluster, automatically handling conflict resolution when the same document is modified simultaneously across different locations. This CouchDB deployment provides a single-node instance with the Fauxton web administration interface, giving you immediate access to database management, document creation, and replication configuration through a browser-based UI. The setup includes persistent data storage and configuration volumes, ensuring your databases and settings survive container restarts while maintaining CouchDB's built-in clustering capabilities for future horizontal scaling. The HTTP/JSON API operates on port 5984, providing direct database access for applications while Fauxton offers visual tools for managing databases, documents, and replication tasks. This configuration is ideal for developers building offline-capable mobile applications, organizations needing reliable multi-site data synchronization, or teams exploring document databases with strong consistency guarantees. CouchDB's unique approach to conflict resolution and its compatibility with PouchDB for client-side storage makes this stack particularly valuable for applications that must function reliably with intermittent connectivity, such as field service apps, collaborative editing tools, or edge computing scenarios where local data access is critical.

Key Features

  • Multi-master replication with automatic conflict resolution across distributed nodes
  • Fauxton web administration interface for visual database and document management
  • RESTful HTTP/JSON API for direct database operations without drivers
  • MapReduce views for complex data aggregation and indexing
  • Mango query language support for MongoDB-style declarative queries
  • MVCC (Multi-Version Concurrency Control) for ACID transaction semantics
  • Built-in change notifications and continuous replication feeds
  • PouchDB synchronization compatibility for offline-first client applications

Common Use Cases

  • 1Mobile applications requiring offline data sync with automatic conflict resolution
  • 2Multi-location businesses needing bidirectional data replication between offices
  • 3Collaborative document editing platforms with real-time synchronization
  • 4IoT edge computing deployments with intermittent connectivity to central servers
  • 5Content management systems requiring version control and distributed publishing
  • 6Field service applications where technicians work offline and sync when connected
  • 7Development teams prototyping document-based applications with immediate API access

Prerequisites

  • Docker Engine 20.10+ and Docker Compose V2 for container orchestration
  • Minimum 512MB RAM available, with 2GB+ recommended for production workloads
  • Port 5984 available for CouchDB HTTP API and Fauxton web interface access
  • Basic understanding of JSON document structure and HTTP REST principles
  • 10GB+ available disk space for database growth and log retention
  • Network connectivity planning if configuring replication to external CouchDB instances

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  couchdb: 
3    image: couchdb:latest
4    container_name: couchdb
5    restart: unless-stopped
6    ports: 
7      - "${COUCHDB_PORT:-5984}:5984"
8    environment: 
9      - COUCHDB_USER=${COUCHDB_USER:-admin}
10      - COUCHDB_PASSWORD=${COUCHDB_PASSWORD:-password}
11    volumes: 
12      - couchdb_data:/opt/couchdb/data
13      - couchdb_config:/opt/couchdb/etc/local.d
14    networks: 
15      - couchdb-network
16
17volumes: 
18  couchdb_data: 
19  couchdb_config: 
20
21networks: 
22  couchdb-network: 
23    driver: bridge

.env Template

.env
1# CouchDB
2COUCHDB_PORT=5984
3COUCHDB_USER=admin
4COUCHDB_PASSWORD=password

Usage Notes

  1. 1Fauxton UI at http://localhost:5984/_utils
  2. 2API at http://localhost:5984
  3. 3Login with admin credentials
  4. 4Built-in replication support

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  couchdb:
5    image: couchdb:latest
6    container_name: couchdb
7    restart: unless-stopped
8    ports:
9      - "${COUCHDB_PORT:-5984}:5984"
10    environment:
11      - COUCHDB_USER=${COUCHDB_USER:-admin}
12      - COUCHDB_PASSWORD=${COUCHDB_PASSWORD:-password}
13    volumes:
14      - couchdb_data:/opt/couchdb/data
15      - couchdb_config:/opt/couchdb/etc/local.d
16    networks:
17      - couchdb-network
18
19volumes:
20  couchdb_data:
21  couchdb_config:
22
23networks:
24  couchdb-network:
25    driver: bridge
26EOF
27
28# 2. Create the .env file
29cat > .env << 'EOF'
30# CouchDB
31COUCHDB_PORT=5984
32COUCHDB_USER=admin
33COUCHDB_PASSWORD=password
34EOF
35
36# 3. Start the services
37docker compose up -d
38
39# 4. View logs
40docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/couchdb-cluster/run | bash

Troubleshooting

  • Error 'COUCHDB_USER must be set': Set both COUCHDB_USER and COUCHDB_PASSWORD environment variables in your .env file
  • Fauxton shows 'Database does not exist' errors: Create databases through the Fauxton interface or HTTP PUT requests to establish initial schema
  • High memory usage during view builds: CouchDB loads entire datasets into memory for MapReduce operations - increase container memory limits or optimize view functions
  • Replication failing with 'unauthorized' errors: Verify target database credentials and ensure the replication user has write permissions on destination
  • Container exits with 'permission denied' on data directory: Check that the couchdb_data volume has proper ownership (UID 5984) or run chown on the volume mount
  • View queries returning inconsistent results: Run view compaction through Fauxton Database tab or trigger manual view rebuilds to resolve index corruption

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

couchdb

Tags

#couchdb#document#nosql#sync#replication

Category

Database Stacks

Related Recipes

Ad Space