Deploy and Host CouchDB on Railway

Apache CouchDB is the document database that speaks plain HTTP and JSON, with a built-in web console (Fauxton) and master-master replication. It is the usual backend for offline-first apps that sync with PouchDB, and for anything that wants a database reachable with nothing but curl.

This template runs CouchDB 3.5 as a single service from a digest-pinned official image: the HTTP API and Fauxton on a Railway domain, an admin account whose password exists from the first boot, and all data on a Railway volume.

About Hosting CouchDB

CouchDB is a document database that speaks HTTP and replicates between nodes and PouchDB clients. It runs as one container with its data on a Railway volume.

Why Deploy CouchDB on Railway

CouchDB on Railway needs a few things handled for you, and this template does them:

It deploys. The most-deployed CouchDB listing on the marketplace builds from public.ecr.aws/bitnami/couchdb:latest, which no longer exists. A fresh deploy of it fails at build with failed to resolve source metadata ... not found before a single container starts (measured 2026-10-09). This template pulls the official couchdb image by digest.
The admin password is generated per deploy. The admin user is admin; the password is in the COUCHDB_PASSWORD variable and is never asked of you. Every request without credentials is refused, so a database created without a security document is not open to the internet (CouchDB's default for a new database is readable and writable by anyone who can reach it). Only /_up stays open, for the health check.
User sessions and replication survive a redeploy. The cookie secret is COUCHDB_SECRET, fixed across deploys, so a session held by a user in _users stays valid after a redeploy (measured). The built-in admin account is the exception: its cookie is signed with a salt that CouchDB regenerates at every boot, so the admin signs in again after a redeploy; basic-auth and API clients are unaffected. The server UUID is stored on the volume, because replication checkpoints are keyed on it and a UUID that changes every deploy makes every replicator start over.
Single-node, ready to use. _users and _replicator are created on first boot; there is no cluster setup step.
Data survives redeploys. The data directory is the Railway volume at /opt/couchdb/data.
Schedulers follow your plan. CouchDB runs on the Erlang VM, which starts one scheduler per CPU it can see, and a Railway container sees the host's. The start command reads the container's CPU limit and caps the schedulers to it.

Common Use Cases

Sync backend for PouchDB and offline-first mobile or web apps
Self-hosted Obsidian LiveSync, Joplin or other note-sync servers that speak the CouchDB protocol
A schemaless JSON store reachable with plain HTTP from any language
Replication hub between edge databases and a central one

Dependencies for CouchDB Hosting

One Railway volume for the data directory (created by the template)

Deployment Dependencies

CouchDB documentation: https://docs.couchdb.org
Official image: https://hub.docker.com/_/couchdb

Implementation Details

Variable	Purpose
`COUCHDB_PASSWORD`	Password of the `admin` user, generated per deploy.
`COUCHDB_SECRET`	Cookie and session signing secret, generated once and kept across deploys.
`COUCHDB_PRIVATE_URL`	Address with credentials for services in the same Railway project.
`COUCHDB_PUBLIC_URL`	Address with credentials over the public domain, for clients outside Railway.

Open https:///_utils and sign in as admin, or from a shell:

curl -u admin: -X PUT https:///mydb
curl -u admin: https:///_all_dbs