A CouchDB Docker container that exits with no logs and keeps restarting

Environment: CouchDB 3.3 (official Docker image) · docker compose · running as the backend for Obsidian Self-hosted LiveSync

TL;DR

If your CouchDB container exits 1, writes nothing at all to its log, and then keeps restarting, check whether the config file is mounted read-only.

# this kills it
volumes:
  - ./local.ini:/opt/couchdb/etc/local.ini:ro

Drop the :ro and it starts:

volumes:
  - ./local.ini:/opt/couchdb/etc/local.ini

The official image's entrypoint prepares its config files before it hands off to CouchDB — fixing up ownership and writing the admin credentials into local.d/docker.ini. On a read-only mount that preparation appears to fail, killing the container before CouchDB starts — which is why there's no CouchDB log to read.

The symptom

I'm writing this from the operational records kept at the time rather than re-running any of it today. The background for the whole series is in Self-hosted Obsidian instead of Notion.

Step one was standing up the CouchDB that would back Obsidian Self-hosted LiveSync. The stack sat under a root-owned path, so the user brought it up with sudo docker compose. The container spun up, exited immediately with code 1, and the restart policy put it straight into a loop.

The problem was that there was nothing to go on. The user pulled the container logs with sudo docker compose logs and got absolutely nothing — no config complaint, no port conflict, no stack trace. Just the exit code.

The tempting wrong turn

With no logs, the instinct is to suspect the CouchDB config. Bad local.ini syntax? A wrong single_node value? Malformed admin credentials? Port already taken? All plausible — and all wrong for this particular symptom.

Here's the tell that pointed me somewhere else: if the CouchDB config were bad, CouchDB would get far enough to complain about it in the log. An empty log means the process never started, which puts the culprit earlier in the startup chain than CouchDB itself — in the container entrypoint.

Root cause: the entrypoint needs the config mount to be writable before CouchDB runs

The official image's entrypoint does housekeeping before exec'ing CouchDB. Part of that is preparing the config directory: normalizing ownership so the in-container couchdb user can read and write those files, and writing the admin credentials you passed in as environment variables into the last file of the config chain (local.d/docker.ini).

Mount local.ini with :ro and the file is read-only inside the container. The step that fails on it is probably the ownership fixup, but with no output at all I couldn't confirm where it actually died. What I can say for sure is narrower: with the :ro gone, the container came up. (Read-only config dropped into local.d can break on the docker.ini write instead — that's #192 below, and that one at least left an error message.)

Whichever step it is, the entrypoint doesn't degrade gracefully: it exits 1, CouchDB never runs, and there is no log. That's all the "silent death" ever was.

This isn't a quirk of one setup; it comes up repeatedly upstream. apache/couchdb-docker issue #204 ("Container exits with no log messages if configuration file is provided") describes the same symptom, and #192 covers the variant where a Kubernetes ConfigMap is mounted read-only over local.d, which surfaces as touch: cannot touch '/opt/couchdb/etc/local.d/docker.ini': Read-only file system — unlike ours, that one at least tells you something.

Worth knowing: Kubernetes ConfigMaps and Docker Swarm secrets mount read-only by default, so config injected either of those ways hits the same wall as a hand-added :ro in compose.

The fix

Remove :ro from the config mount. I proposed the change, the user applied it, and the container came straight up.

services:
  couchdb:
    image: couchdb:3.3
    restart: unless-stopped
    ports:
      - "127.0.0.1:5984:5984"
    environment:
      COUCHDB_USER: ${COUCHDB_USER}
      COUCHDB_PASSWORD: ${COUCHDB_PASSWORD}
    volumes:
      - ./local.ini:/opt/couchdb/etc/local.ini   # no :ro here
      - couchdb-data:/opt/couchdb/data

Two things in that snippet are worth copying:

Bind to 127.0.0.1:5984:5984, not 5984:5984. The short form publishes on every interface on the host. Remote access should come from a deliberate path — tailscale, in this stack — rather than a port you opened by accident.
Keep the credentials in .env. If you hardcode them in the compose file or in local.ini, they go straight into git.

Bonus: a file whose name starts with `_` won't sync

This one turned up much later in the same stack, but it belongs right next to the entrypoint bug: a file or folder in the vault whose name starts with _ quietly stops syncing.

CouchDB reserves document IDs beginning with an underscore for its own use (_design, _local, and friends). When the note goes up as a document, the leading _ makes the ID invalid — I never confirmed whether it's stripped or rejected outright — and that one note drops out of sync. There's no error popup. It just never arrives, which is the nasty part.

A session running on the server walked into this later by naming a watchdog file _pull_heartbeat.md. The rule works out like this:

_note.md → broken (leading underscore)
0_Dashboard, 1_Projects → fine (a digit prefix is irrelevant)
pull_heartbeat.md, daily_log.md → fine (an underscore anywhere else is harmless)

Only the first character counts.

Dropping the underscore wasn't the end of it, though. pull_heartbeat.md synced fine — but a file whose contents change every 10 minutes, sitting in plain sight in the vault, started throwing conflicts in Obsidian on other devices. The answer was to make it a dotfile, .pull_heartbeat.md: livesync-bridge, the headless service that mirrors CouchDB documents onto the server's filesystem, syncs dotfiles, and Obsidian clients ignore hidden files by default. That only holds while the client's "sync hidden files" option stays off (the default) — turn it on and the conflicts come right back. That one gets its own post later in this series.

Takeaways / checklist

A container that dies without logging anything should make you suspect the entrypoint, not the app. A misconfigured app usually survives long enough to complain. Silence usually means it never ran.
Don't inject config read-only into the official CouchDB image. :ro in compose, Kubernetes ConfigMaps, and Swarm secrets all end up the same way, because the entrypoint has to be able to write to that mount before startup.
In any note system backed by CouchDB, don't start file or folder names with _. The failure is silent and limited to that note — the rest of the vault keeps syncing — so you'll waste real time later wondering why that one never showed up.

One caveat on scope: this is what the user and I actually hit and worked out, not a claim that it's the only answer. The upstream threads do mention a workaround — an init container that copies the config in, which is what the official helm chart does — but I never tried it on this stack.