Key conclusion: do not call the image broken from the install error alone. Self-hosted LiveSync needs working CouchDB credentials, writable persistent storage, initialization, CORS, and a reachable endpoint. A one-click app template can still require those values.
Set the required CouchDB variables
Current upstream LiveSync CouchDB variables require administrator credentials and a database name:
COUCHDB_USER=admin
COUCHDB_PASSWORD=strong-random-password
COUCHDB_DATABASE=obsidiannotesRead container logs before editing randomly
docker ps -a | grep -i couch
docker logs --tail 200 <container-name>Look for missing variables, permission errors, config mount failures, initialization failures, or port conflicts.
Persistent storage must be writable
The upstream CouchDB storage setup notes that data/config directories can be owned by UID 5984. Incorrect ownership can stop the container.
Verify CouchDB before Obsidian
curl -u admin:YOUR_PASSWORD http://SERVER_IP:5984/_upThe upstream CouchDB health check expects a healthy status before plugin configuration.
Initialize the LiveSync database
A running CouchDB process is not the whole setup. Run the current upstream initialization path so required database/config values exist before connecting the Obsidian plugin.
Remote sync needs a safe HTTPS path
The upstream project now provides Caddy, Tailscale, and Cloudflare profiles. Use plain HTTP only for local testing; remote/mobile sync should use a supported HTTPS route.
BigBear currently lists an Obsidian LiveSync package based on CouchDB. Compare the generated compose against upstream variables rather than assuming either side is correct.
The ZimaOS app catalog includes Obsidian-related workloads, and CasaOS Docker configuration helps explain template-versus-runtime settings.
ZimaBoard 2 is sufficient for this lightweight database workload; storage durability matters more than raw compute.
Compare the template with current upstream compose
The current upstream compose starts CouchDB with required username/password variables, persistent data, and a dedicated LiveSync configuration file. If a community template differs, identify the difference before labeling the container image faulty. The image, compose template, and application configuration are three separate layers.
Do not force the CouchDB container user casually
Current upstream compose explicitly warns against setting a fixed user: value because the CouchDB entrypoint starts with enough privilege to write its configuration and then drops to the CouchDB UID. A template that overrides this behavior can create permission failures during startup.
Check CORS after the health endpoint works
A healthy /_up response proves CouchDB is running, not that Obsidian clients can use it. Test response headers with an Obsidian origin and confirm the LiveSync configuration allows the expected desktop/mobile origins.
Keep the database off the open internet
CouchDB port 5984 is a database endpoint, not a consumer sharing page. For remote sync, prefer the upstream supported HTTPS patternsโCaddy, Tailscale, or Cloudflareโrather than a raw router forward to 5984.
Use this troubleshooting order
- Container stays running.
-
/_upreturns healthy with credentials. - Persistent data survives restart.
- Initialization completes.
- CORS is correct.
- HTTPS endpoint works remotely.
- Obsidian plugin URI/user/password/database match server values.
Skipping directly to plugin settings before steps 1โ5 makes troubleshooting much harder.
FAQ
Is the BigBear image definitely faulty?
The source discussion did not prove that. Compare its compose with current upstream requirements first.
Why can CouchDB run while Obsidian fails?
Database initialization, CORS, credentials, database name, and endpoint URL must still match.
