Deploy CouchDB HA

Deploy and Host CouchDB on Railway

Apache CouchDB is a document database that stores JSON, speaks plain HTTP, and treats replication as a first-class feature rather than an add-on. Every document is reachable at a URL, and any two CouchDB instances — or a server and a PouchDB database inside a browser tab — sync in either direction and resolve conflicts deterministically. That is why teams self-host CouchDB for offline-first apps, field data collection, and anything that must keep working when the network does not.

Deploy CouchDB on Railway in the shape the project recommends for production: a three-node cluster, not a single container. couchdb-node1, couchdb-node2 and couchdb-node3 each run CouchDB 3.5 with their own volume and join into one cluster over Railway's private network. couchdb-lb is a small Caddy service that holds the public domain and round-robins across the nodes, health-checking each so one that goes away stops receiving traffic. Databases get two shards and three replicas, so losing a node still leaves a write quorum.

Getting Started with CouchDB on Railway

Set a username and password when you deploy; everything else has a working default. Open the public URL of couchdb-lb and your browser will prompt for those credentials — CouchDB is locked down from the first boot, so there is no open window and no default password to change. Visit /_utils/ for Fauxton, the built-in admin interface. A good first check is /_membership: it should list three entries under both cluster_nodes and all_nodes, confirming the nodes are genuinely connected, not merely registered.

Then create a database and write a document. Fauxton's Run A Query with Mango panel filters documents with a JSON selector and reports how many keys it examined — the quickest way to tell whether a query used an index. Design documents hold map/reduce views for aggregations Mango cannot express. Applications use the same URL: curl, fetch, PouchDB and every client library speak the same HTTP API.

About Hosting Apache CouchDB

CouchDB solves a problem most databases push back onto the application: keeping copies of the same data in sync across machines that are not always reachable. Its replication protocol is incremental, resumable, bidirectional and conflict-aware, so a laptop offline for a week reconnects and reconciles without custom merge code. Self-hosting matters because the sync endpoint is the product, and Apache-2.0 puts no edition gate on clustering.

Key features:

• HTTP/JSON API — no proprietary wire protocol or driver required
• Multi-master replication with conflict detection and revision history
• Mango, a declarative JSON query language, with secondary indexes
• JavaScript map/reduce views for aggregation and materialised indexes
• Changes feeds, long-poll and continuous, for reactive apps
• PouchDB compatibility, so browsers and React Native apps sync natively

The Railway architecture is four services. The three couchdb-node services are the database: they share one cluster, shard each database across the group, and replicate every shard to all three. couchdb-lb terminates the public domain, spreads requests over the nodes, and probes each node's liveness endpoint so traffic skips one that is restarting. Only the load balancer is reachable from the internet.

Why Deploy CouchDB on Railway

Railway removes the work that makes a clustered database awkward to run.

• Three nodes with persistent volumes provisioned in one click
• Private networking between nodes, with no exposed database ports
• HTTPS and a public domain handled at the edge
• Health checks that take a restarting node out of rotation
• Redeploy on push from the source repository

Common Use Cases

• Offline-first mobile and web apps — PouchDB stores data on the device and syncs when connectivity returns, with no bespoke merge logic.
• Field data collection — surveys and inspections on tablets that spend hours disconnected, reconciling in bulk.
• Retail and point-of-sale — each till keeps a local replica, so sales continue through an outage.
• Document and content stores — schemaless records with attachments, revision history and an HTTP API any language can call.

Dependencies for CouchDB

• couchdb:3.5 — the official Apache CouchDB image, run by all three node services
• caddy:2-alpine — the load balancer in front of the cluster
• One 5 GB volume per node, mounted at /opt/couchdb/data

Environment Variables Reference

Deployment Dependencies

• Source repository:
• Upstream project:
• Official image:
• Documentation:

Hardware Requirements for Self-Hosting CouchDB

Figures are per node; the cluster runs three.

Views are materialised on disk and rebuilt when a design document changes, so budget storage for indexes too.

Self-Hosting CouchDB

CouchDB runs from the official image with two required variables. A single-node instance for local development, in Docker:

docker run -d --name couchdb -p 5984:5984 \
  -e COUCHDB_USER=admin \
  -e COUCHDB_PASSWORD=please-change-me \
  -v couchdb-data:/opt/couchdb/data \
  couchdb:3.5

Then create a database and write a document over HTTP. These curl calls hit the same API the Railway deployment exposes:

curl -u admin:please-change-me -X PUT http://127.0.0.1:5984/notes

curl -u admin:please-change-me -X POST http://127.0.0.1:5984/notes \
  -H 'Content-Type: application/json' \
  -d '{"title":"First note","tags":["draft"]}'

curl -u admin:please-change-me http://127.0.0.1:5984/notes/_all_docs

Replication between two servers is one request naming both endpoints. Local database names are not accepted as replication endpoints in CouchDB 3.x — use full URLs on both sides.

How Much Does CouchDB Cost to Self-Host?

CouchDB is free and open source under the Apache License 2.0. There is no paid edition and no feature behind a licence key — clustering, replication and Mango queries are in the same build. Self-hosting on Railway costs only the compute, memory and volume storage the four services use, so the bill scales with your data rather than with query volume.

CouchDB vs MongoDB

MongoDB is stronger for high-throughput server-side workloads. CouchDB wins when clients need their own replica, when sync must survive long disconnections, or when you want an HTTP API with no driver in between.

FAQ

What is CouchDB? Apache CouchDB is an open-source document database that stores JSON documents, exposes them over an HTTP API, and replicates between instances in either direction with automatic conflict detection.

What does this Railway template deploy? Three CouchDB 3.5 nodes, each with its own persistent volume, joined into one cluster, plus a Caddy load balancer that holds the public domain and distributes requests across them.

Why does the template run three nodes instead of one? CouchDB's documentation strongly recommends a minimum of three. With three replicas of every shard, a majority still exists when one node is unavailable, so reads and writes continue through a restart or failure.

Why is there a separate load balancer service? A Railway domain points at one service. The load balancer gives the cluster a single public endpoint, spreads requests over all three nodes, removes one from rotation when its health check fails, and keeps the nodes off the public internet.

How do I connect a PouchDB client to self-hosted CouchDB? Point PouchDB at the public URL plus the database name, and set COUCHDB_CORS_ORIGINS to your app's origin so the browser is allowed to talk to it. From there db.sync() replicates in both directions.