$docker.recipes

CouchDB Cluster

beginner

Apache CouchDB document database with Fauxton UI.

[i]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

  • [1]Mobile applications requiring offline data sync with automatic conflict resolution
  • [2]Multi-location businesses needing bidirectional data replication between offices
  • [3]Collaborative document editing platforms with real-time synchronization
  • [4]IoT edge computing deployments with intermittent connectivity to central servers
  • [5]Content management systems requiring version control and distributed publishing
  • [6]Field service applications where technicians work offline and sync when connected
  • [7]Development 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
[!]

WARNING: 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

[i]Usage Notes

  1. [1]Fauxton UI at http://localhost:5984/_utils
  2. [2]API at http://localhost:5984
  3. [3]Login with admin credentials
  4. [4]Built-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