fix(docker): default to serve and move the database to /data

[blueagledev]

Two Dockerfile fixes plus the README lines that go with them. Found while evaluating
korrosync as the sync server for my own ebook setup — I built the image and ran it, though I
am not running korrosync day to day — and independent of the timestamp PR (#132). The analysis and the patch were produced with AI assistance and directed by me;
what was executed rather than asserted is under Checks.

1. The image has no runnable default command

Cli::command is a required subcommand
(cli.rs#L10-L11),
and the Dockerfile sets ENTRYPOINT with no CMD
(Dockerfile#L50),
so the README's own run line
(README.md#L77-L82)
exits 2 with a usage dump. Built from master:

$ docker run --rm -v $(pwd)/data:/data korrosync:master
KOReader synchronization server

Usage: korrosync [OPTIONS] <COMMAND>

Commands:
  serve  Start the sync server
  user   User management commands
  db     Database maintenance commands
  help   Print this message or the help of the given subcommand(s)
...
exit=2

CMD ["serve"] supplies the default. Arguments replace CMD and not ENTRYPOINT, so the
subcommands keep working. Built from this branch:

$ docker run -d --name ks -v $(pwd)/data:/data korrosync:branch
f35b06cbd156ad4971561180637208f50b4245475266aeb1a5389809bd8748bd
$ docker logs ks
2026-08-15T20:05:35.224814Z  INFO korrosync: Server listening on 0.0.0.0:3000

$ docker run --rm -v $(pwd)/data:/data korrosync:branch db info
Database path: /data/db.redb
Database size: 1056768 bytes
Users: 0

2. The default database path is inside the container layer

KORROSYNC_DB_PATH defaulted to /db.redb
(Dockerfile#L44),
which is in the writable container layer. docker rm plus a recreate drops it, which shows
up as 401 Invalid credentials and reads like a password problem rather than an empty
database. From the master image:

$ docker run --name ksm korrosync:master user create -u alice -p secret
User 'alice' created successfully
$ docker rm ksm
ksm
$ docker run --name ksm korrosync:master user list
No users found

On this branch the same sequence against a mounted /data keeps the user, with no -e
flag:

$ docker run --rm -v $(pwd)/data:/data korrosync:branch user create -u alice -p secret
User 'alice' created successfully
$ docker run --rm -v $(pwd)/data:/data korrosync:branch user list
USERNAME             LAST ACTIVITY
----------------------------------------
alice                never

Total: 1 user(s)

Anyone following your instructions was never at risk: README.md#L77-L82 passes both
-v $(pwd)/data:/data and -e KORROSYNC_DB_PATH=/data/db.redb, which puts the database on
the bind mount. The problem is that the default only works if you copy that line verbatim,
and that the -e flag exists solely to compensate for a default pointing somewhere unsafe.
Making /data/db.redb the image default removes the trap, lets the -e line go, and lines
the image up with the application default of data/db.redb
(config.rs#L28).

No VOLUME declaration

My first draft added VOLUME ["/data"] and I dropped it. Checked with a throwaway image
that appends to /data/db on every run: a plain docker run attaches a fresh anonymous
volume, so the file was empty again after docker rm and a recreate, and the two cycles
left two dangling volumes behind. It also cannot be undeclared downstream. The default path
plus one README sentence is the whole fix.

Breaking change

Moving the default strands the database of anyone who relied on /db.redb, and it presents
as exactly the 401 Invalid credentials this PR is fixing. The commit therefore carries a
BREAKING CHANGE: footer, and the README has the upgrade line:

docker cp korrosync:/db.redb ./data/db.redb

That footer will make release-plz cut a minor bump rather than a patch, for a change that
touches no Rust. If you would rather not have that, drop the footer and I will fold the
warning into the release notes by hand instead.

Checks

No .rs files change, so the Rust CI path filters skip this PR. Run anyway in nix develop, on this branch:

• cargo test: 43 unit, 39 integration and 19 doc tests, all pass
• cargo fmt --check, cargo clippy -- -D warnings, cargo machete: clean
• cargo deny check advisories: fails, and fails identically on master, with
  RUSTSEC-2026-0233, RUSTSEC-2026-0234 and RUSTSEC-2026-0235 against rkyv 0.8.16 plus a
  yanked spin

Both images were built from this repo and exercised locally, master and this branch; every
transcript above is from those runs.

[Copilot]

Pull request overview

This PR adjusts the container UX defaults for Korrosync so the published Docker image runs successfully without requiring an explicit subcommand, and so the default database location aligns with a persistent mount point (/data) rather than the ephemeral container layer.

Changes:

• Add CMD ["serve"] so docker run korrosync starts the server by default while preserving subcommand behavior.
• Change the image default KORROSYNC_DB_PATH to /data/db.redb (from /db.redb) to encourage persistence via a bind mount.
• Update README Docker run examples, add a subcommand example, and document the upgrade path for older images that used /db.redb.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
README.md	Removes the redundant KORROSYNC_DB_PATH env var from run examples, adds subcommand usage example, and documents upgrade guidance for the old /db.redb default.
Dockerfile	Sets safer default DB path (/data/db.redb) and adds CMD ["serve"] so the image has a runnable default command.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.