CouchDB CouchDB

Multi-primary syncing database

Seamless multi-primary syncing database with an intuitive HTTP/JSON API, designed for reliability

Used by Obsidian LiveSync

References

Backup

backup.yaml uses CouchDB’s supported append-only live-file backup each night, copying indexes before shards/system DBs and runtime config into ${DB_BACKUP_ROOT}/database-couchdb/. Every staged file is checked in B2 before local retention. Obsidian’s vault uses the separate repos source. See the backup guide for commands, retention and snapshot selection.

Recovery

  1. Retrieve the export’s staged couchdb/data/, couchdb/etc/ and manifest and verify every recorded hash. Keep shards, indexes and system metadata together; restoring only visible user database files is insufficient.
  2. Stop the destination CouchDB. Install the staged data/configuration at the configured /opt/couchdb/data and /opt/couchdb/etc/local.d mounts, retaining node identity, expected ownership and original credentials. Use a compatible image matching the backup’s deployed version.
  3. Start CouchDB and check _users, _replicator and the expected user database inventory before reconnecting Obsidian LiveSync.

CouchDB’s append-only live-copy method is an engine-specific exception, not a reason to copy arbitrary running databases. DB/config/vault captures are not one global transaction; the vault’s repos restore point must be selected separately.

name: couchdb
services:
  couchdb:
    image: couchdb:3.5.3@sha256:3611ce43bd32fe2368997fd41ec6e7270ec8d84aa5fc13c9828e5b15fd6bafe8
    container_name: couchdb
    restart: unless-stopped
    # kics-scan ignore-block
    environment:
      COUCHDB_USER: ${COUCHDB_USER:?CouchDB admin user must be set}
      COUCHDB_PASSWORD: ${COUCHDB_PASSWORD:?CouchDB admin password must be set}
    volumes:
      - ${DOCKER_VOLUMES}/couchdb/data:/opt/couchdb/data
      - ${DOCKER_VOLUMES}/couchdb/etc:/opt/couchdb/etc/local.d
    networks:
      - proxy
    labels:
      traefik.enable: true
      traefik.http.routers.couchdb.middlewares: localaccess@file
      traefik.http.services.couchdb.loadbalancer.server.port: 5984
      homepage.group: Storage
      homepage.name: CouchDB
      homepage.icon: couchdb.png
      homepage.href: https://couchdb.${MYDOMAIN}/
      homepage.description: Multi-primary syncing database

networks:
  proxy:
    external: true