--- title: "Deploy CouchDB" description: "CouchDB 3.5 document database with Fauxton, a generated admin and a volume" category: "Storage" url: https://railway.com/deploy/couchdb-1 --- # Deploy CouchDB CouchDB 3.5 document database with Fauxton, a generated admin and a volume **[Deploy CouchDB on Railway](https://railway.com/template/couchdb-1)** Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/couchdb-1/manifest.json - **Creator:** Agaz Self-Host - **Category:** Storage ## Template content ### CouchDB https://cdn.jsdelivr.net/gh/selfhst/icons/svg/couchdb.svg - **Image:** couchdb:3.5.3@sha256:907eab5b7e55ab7cfd241d39b90b2a335ea40bef82acee5a37388c08bf201dda - **Start command:** `/bin/sh -c 'set -e; D=/opt/couchdb/data/.railway; L=/opt/couchdb/etc/local.d; export COUCHDB_USER="${COUCHDB_USER:-admin}"; mkdir -p "$D"; touch "$D/runtime.ini"; sed -i "/^\[admins\]/,/^\[/{/^$COUCHDB_USER *=/d}" "$D/runtime.ini"; ln -sfn "$D/runtime.ini" "$L/zz-runtime.ini"; { printf "[couchdb]\nsingle_node = true\n[cluster]\nn = 1\n[chttpd]\nport = %s\nbind_address = ::\n" "${PORT:-5984}"; if [ -n "$COUCHDB_CORS_ORIGINS" ]; then printf "enable_cors = true\n[cors]\norigins = %s\ncredentials = true\nmethods = GET, PUT, POST, HEAD, DELETE\nheaders = accept, authorization, content-type, origin, referer\n" "$COUCHDB_CORS_ORIGINS"; fi; } > "$L/railway.ini"; 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 an open-source document database that stores JSON documents and serves them over a plain HTTP API. It replicates between servers and devices, so apps built with PouchDB or other CouchDB-compatible clients can work offline and sync later. It ships with Fauxton, a web admin interface. ## About Hosting CouchDB Hosting CouchDB means running the database server with an admin account, keeping its data directory on persistent storage, and finishing the single-node setup that creates the `_users` and `_replicator` system databases. This template runs the official CouchDB 3.5.3 image pinned by digest. It creates the admin from a generated password, finishes single-node setup on first start and keeps the data on a Railway volume. Railway's health check uses `/_up`. Everything else needs a login: anonymous users can't list or create databases, sign up in `_users`, or read and write documents. CORS for browser and PouchDB clients is off unless you list allowed origins. ## Common Use Cases * Sync backend for offline-first web and mobile apps built with PouchDB * Self-hosted sync server for Obsidian LiveSync and other CouchDB-based tools * JSON document store with an HTTP API, views and Mango queries for small and medium apps ## Dependencies for CouchDB Hosting * A Railway volume mounted at `/opt/couchdb/data` (created by the template) * The official `couchdb` Docker image (3.5.3) ### Deployment Dependencies * CouchDB documentation: https://docs.couchdb.org/en/stable/ * CouchDB 3.5.3 release: https://github.com/apache/couchdb/releases * Official Docker image: https://hub.docker.com/_/couchdb * PouchDB (browser and mobile client): https://pouchdb.com/ ### Implementation Details * **Login:** open `https://YOUR-DOMAIN.up.railway.app/_utils/` for Fauxton. The username is `COUCHDB_USER` (default `admin`), and the password is the generated `COUCHDB_PASSWORD` on the CouchDB service's Variables tab. * **Changing the password:** change `COUCHDB_PASSWORD` and redeploy. The new value replaces the old one on the next start. * **Other services on Railway** can connect over the private network with `http://${{CouchDB.COUCHDB_USER}}:${{CouchDB.COUCHDB_PASSWORD}}@${{CouchDB.RAILWAY_PRIVATE_DOMAIN}}:5984`. * **CORS:** to let browser apps connect directly, set `COUCHDB_CORS_ORIGINS` to a comma-separated list of origins, for example `https://app.example.com`, and redeploy. Prefer exact origins over `*`. * **Config persistence:** changes made in Fauxton's Configuration page or through `/_node/_local/_config` (extra server admins, for example) are saved on the volume and survive redeploys. A setting changed there takes precedence over the template's variables. The one exception is the main admin's password, which always follows `COUCHDB_PASSWORD` on each start. * This is a single-node server. Back up important data with replication to a second CouchDB server. ## Why Deploy CouchDB on Railway? Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it. By deploying CouchDB on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway. ## Similar templates - [RustFS | (Just Updated) S3 Object Store, Public URL and Keys Set](https://railway.com/deploy/rustfs-or-just-updated-s3-object-store-p) — S3-compatible object store, keys and public URL preset, volume kept - [TimescaleDB](https://railway.com/deploy/timescaledb-railway-template) — A PostgreSQL-based time-series database for analytics on Railway. - [Neo4j 2026.10 Community](https://railway.com/deploy/neo4j-202610-community) — Neo4j graph database with APOC, Browser, Bolt TCP proxy and a volume Open this page in a browser: https://railway.com/deploy/couchdb-1