---
title: "Deploy CouchDB | (Just Updated) NoSQL Database, Admin Password From Boot, Data Survives Redeploys"
description: "CouchDB 3.5 that deploys. Locked from boot, data survives redeploys"
category: "Storage"
url: https://railway.com/deploy/couchdb-or-just-updated-nosql-database-a
---

# Deploy CouchDB | (Just Updated) NoSQL Database, Admin Password From Boot, Data Survives Redeploys

CouchDB 3.5 that deploys. Locked from boot, data survives redeploys

**[Deploy CouchDB | (Just Updated) NoSQL Database, Admin Password From Boot, Data Survives Redeploys on Railway](https://railway.com/template/couchdb-or-just-updated-nosql-database-a)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/couchdb-or-just-updated-nosql-database-a/manifest.json

- **Creator:** SuperSlowSloth
- **Category:** Storage

## Template content

### couchdb

- **Image:** couchdb:3.5.2.1@sha256:5fc596110eac7f412173a7d9de14f70aa5d3e816790fb6e70642755d4a4cf464
- **Start command:** `/bin/sh -c 'set -e; M=$(cat /sys/fs/cgroup/memory.max 2>/dev/null || echo max); Q=$(cut -d" " -f1 /sys/fs/cgroup/cpu.max 2>/dev/null || echo max); if [ "$Q" != max ]; then CORES=$(( (Q + 99999) / 100000 )); else CORES=$(nproc); fi; [ "$CORES" -lt 1 ] && CORES=1; D=/opt/couchdb/data; mkdir -p "$D"; if [ ! -s "$D/.railway-uuid" ]; then tr -d - < /proc/sys/kernel/random/uuid > "$D/.railway-uuid"; fi; UUID=$(cat "$D/.railway-uuid"); if [ "$(cat /proc/sys/net/ipv6/conf/all/disable_ipv6 2>/dev/null || echo 1)" = 0 ]; then BIND=::; else BIND=any; fi; export COUCHDB_USER=admin ERL_FLAGS="+S $CORES:$CORES"; printf "[couchdb]\nsingle_node = true\nuuid = %s\n\n[chttpd]\nport = %s\nbind_address = %s\nrequire_valid_user_except_for_up = true\n" "$UUID" "${PORT:-5984}" "$BIND" > /opt/couchdb/etc/local.d/10-railway.ini; echo "[railway] couchdb port=${PORT:-5984} bind=$BIND schedulers=$CORES uuid=$UUID memory.max=$M owner=$(stat -c %u:%g $D)"; exec tini -- /docker-entrypoint.sh /opt/couchdb/bin/couchdb'`
- **Health check:** /_up
- **Public domain:** Yes

## Documentation

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

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


## 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-or-just-updated-nosql-database-a