A plug-and-play Unraid Community Applications template for Apache CouchDB (3.x) - the HTTP/JSON document database behind Obsidian LiveSync and many offline-first apps. Wraps the official couchdb image, fixed so your data and config actually survive a container recreate or update, with CORS documented for LiveSync.

Table of Contents

1. What is this?
2. Why not the old CouchDB template?
3. Quick Start on Unraid
4. First-run setup (single node)
5. CORS for Obsidian LiveSync
6. Configuration
7. Backup & restore
8. Reverse proxy & HTTPS
9. Updating
10. Troubleshooting
11. License

1. What is this?

An Unraid Community Applications template for Apache CouchDB. It deploys the official couchdb image (currently 3.x) with the two volume mounts the modern image actually needs, so your databases and settings persist. CouchDB is a document database that speaks plain HTTP and stores JSON, and it is the standard sync backend for Obsidian LiveSync.

2. Why not the old CouchDB template?

The long-standing community CouchDB template was written for CouchDB 1.x and maps /usr/local/var/lib/couchdb. The official image has been 3.x for years, and 3.x stores things in different places:

Two things go wrong with the old template:

1. Your databases live in an anonymous Docker volume. Because /opt/couchdb/data is not mapped, the real data sits in an unnamed volume - not in appdata, not in your backups, and gone the moment you recreate or update the container.
2. CORS keeps disabling itself. The image regenerates local.d/docker.ini from the admin environment variables on every start. A restart keeps the file, but a recreate wipes any CORS you set in Fauxton. Since local.d is not mapped, there is nowhere for a persistent CORS file to live.

This template maps both paths to appdata, so nothing is lost and CORS stays put.

3. Quick Start on Unraid

1. Apps tab -> search CouchDB (by junkerderprovinz) -> Install.
2. Set an Admin User and a strong Admin Password (CouchDB 3.x will not start without an admin; "admin party" is disabled).
3. Apply, wait for the pull, then open Fauxton at http://SERVER_IP:5984/_utils/.
4. Do the first-run single-node setup (one command) so the system databases exist.
5. Using Obsidian LiveSync or another browser client? Add the CORS file.

4. First-run setup (single node)

A fresh CouchDB 3.x node needs its system databases (_users, _replicator, _global_changes) created once. The cleanest way is the single-node setup call - run it on the Unraid console after the container is up (replace SERVER_IP and PASSWORD):

curl -X POST -u admin:PASSWORD \
  http://SERVER_IP:5984/_cluster_setup \
  -H "Content-Type: application/json" \
  -d '{"action":"enable_single_node","bind_address":"0.0.0.0","username":"admin","password":"PASSWORD","port":5984,"singlenode":true}'

Verify it worked:

curl http://SERVER_IP:5984/_up
curl -u admin:PASSWORD http://SERVER_IP:5984/_all_dbs

_up should return {"status":"ok"} and _all_dbs should list _replicator and _users. The "_users database does not exist" warning in the log is gone once this is done.

5. CORS for Obsidian LiveSync

Browser clients (Obsidian LiveSync, the Obsidian mobile app, any web app) need CORS enabled on CouchDB. Do not set it in Fauxton - that writes to docker.ini, which the image regenerates on the next recreate. Instead add a separate drop-in file that the image never touches.

Create local.d/10-cors.ini in the config folder you mapped (/mnt/user/appdata/couchdb/local.d/10-cors.ini) with exactly this content:

[chttpd]
enable_cors = true

[cors]
origins = *
credentials = true
headers = accept, authorization, content-type, origin, referer
methods = GET, PUT, POST, HEAD, DELETE

Then restart the container. CORS now survives restarts and recreates, because it lives in its own file that the entrypoint leaves alone.

Tighter origins. origins = * is the simplest and works. To lock it down to Obsidian only, replace that line with: origins = app://obsidian.md,capacitor://localhost,http://localhost

In LiveSync, point the URI at http://SERVER_IP:5984 (or your HTTPS domain), enter the admin user and password, and set a database name (LiveSync creates it on first sync). For the mobile app you generally need HTTPS - see Reverse proxy & HTTPS.

6. Configuration

Every field is shown in the template. Fields you rarely touch (the cookie secret) are under Show more settings.

Need another CouchDB setting? Either add a variable with Unraid's Add another Path, Port, Variable..., or drop another .ini into the mapped local.d folder (e.g. 20-tuning.ini).

7. Backup & restore

Everything that matters is in the two mapped folders under /mnt/user/appdata/couchdb:

• data/ - all your databases.
• local.d/ - your config, including 10-cors.ini and the admin docker.ini.

Back up that whole couchdb appdata folder (the Unraid CA Backup plugin or any file backup does the job). To restore, drop the folders back and recreate the container. For a logical, version-independent backup you can also replicate databases out with CouchDB's own _replicate, or dump a database over HTTP.

8. Reverse proxy & HTTPS

CouchDB serves plain HTTP on 5984. The Obsidian mobile app (and good hygiene generally) wants HTTPS, so put it behind a reverse proxy (SWAG / Nginx Proxy Manager / Traefik):

• Proxy https://couchdb.mydomain.tld -> http://SERVER_IP:5984.
• Point LiveSync's URI at the https:// domain.
• Keep CouchDB itself on the LAN; let the proxy terminate TLS.

CouchDB is a database with a full HTTP API - never expose port 5984 straight to the internet. Always front it with a proxy and a strong admin password.

9. Updating

CouchDB updates by image: hit Force Update in the Unraid Docker tab (or change the :latest tag on the Repository field to pin a specific version). Your data and config live in appdata, so they survive updates. CouchDB 3.x is backward compatible across minor releases; read the upstream release notes before a major jump.

10. Troubleshooting

11. License

This template is MIT-licensed (see LICENSE). Apache CouchDB itself is a project of the Apache Software Foundation, distributed under the Apache License 2.0; this repo only packages it for Unraid.