---
title: "Deploy CouchDB HA"
description: "Clustered CouchDB: Document database with load balancing, volumes & HA"
category: "Storage"
url: https://railway.com/deploy/couchdb-ha
---

# Deploy CouchDB HA

Clustered CouchDB: Document database with load balancing, volumes & HA

**[Deploy CouchDB HA on Railway](https://railway.com/template/couchdb-ha)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/couchdb-ha/manifest.json

- **Creator:** A3A
- **Category:** Storage
- **Total deploys:** 1

## Template content

### couchdb-node3 https://raw.githubusercontent.com/gridalpha/couchdb-railway/main/assets/couchdb.svg

- **Source:** https://github.com/gridalpha/couchdb-railway
- **Health check:** /_up

### couchdb-node2 https://raw.githubusercontent.com/gridalpha/couchdb-railway/main/assets/couchdb.svg

- **Source:** https://github.com/gridalpha/couchdb-railway
- **Health check:** /_up

### couchdb-node1 https://raw.githubusercontent.com/gridalpha/couchdb-railway/main/assets/couchdb.svg

- **Source:** https://github.com/gridalpha/couchdb-railway
- **Health check:** /_up

### couchdb-lb https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/caddy.svg

- **Source:** https://github.com/gridalpha/couchdb-railway
- **Health check:** /healthz
- **Public domain:** Yes

## Documentation

# 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.

![Three CouchDB nodes behind a Caddy load balancer on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789272241/couchdb-architecture.webp)

## 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.

![Fauxton listing the library and CouchDB system databases](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789272244/couchdb-fauxton-databases.webp)
![Book documents with author and tag fields in Fauxton](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789272245/couchdb-library-documents.webp)
![Mango query returning two Le Guin novels with execution stats](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789272247/couchdb-mango-query.webp)
![Map/reduce view emitting book copies grouped by tag](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789272248/couchdb-view-by-tag.webp)

## 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

| Variable | Description |
|---|---|
| `COUCHDB_USER` | Administrator username for the cluster |
| `COUCHDB_PASSWORD` | Administrator password; set this at deploy time |
| `COUCHDB_SECRET` | Signs session cookies. Changing it logs everyone out |
| `COUCHDB_ERLANG_COOKIE` | Shared token the nodes authenticate with |
| `COUCHDB_UUID` | Server identifier. Must be identical on every node |
| `COUCHDB_CLUSTER_N` | Replicas of each shard. Defaults to `3` |
| `COUCHDB_CLUSTER_Q` | Shards per database. Defaults to `2` |
| `COUCHDB_MAX_DOCUMENT_SIZE` | Largest accepted document, in bytes |
| `COUCHDB_LOG_LEVEL` | `warning` by default; raise to `info` to debug |
| `COUCHDB_CORS_ORIGINS` | Set to enable CORS for browser clients such as PouchDB |

### Deployment Dependencies

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

## Hardware Requirements for Self-Hosting CouchDB

Figures are per node; the cluster runs three.

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 0.5 vCPU | 2 vCPU |
| RAM | 512 MB | 2 GB |
| Storage | 5 GB volume | 20 GB+, sized to your documents and views |
| Runtime | Erlang/OTP 26 (bundled in the image) | Same |

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

| | CouchDB | MongoDB |
|---|---|---|
| API | HTTP and JSON | Binary wire protocol, driver required |
| Replication | Multi-master, bidirectional | Primary–secondary with failover |
| Offline sync | Native, via PouchDB | Not built in |
| Query language | Mango plus map/reduce views | Aggregation framework |
| Licence | Apache-2.0 | SSPL |

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.


## Similar templates

- [Garage S3 Storage](https://railway.com/deploy/garage-s3-storage) — Ultra-light S3 server: fast, open-source, plug-and-play.
- [Redis](https://railway.com/deploy/redis-1) — Self Host Latest Redis with Railway
- [EasyImg](https://railway.com/deploy/easyimg) — Simple self-hostable Nuxt.js personal image hosting system.

Open this page in a browser: https://railway.com/deploy/couchdb-ha