Lab

cobiserver

A sync server for KOReader that you run yourself.

Question
Can you replace the official KOReader sync server without changing anything in the app?
Result
Yes. It speaks the same protocol, and adds what that protocol leaves out: a web page to register, change your password or get it back.

What it does

KOReader can sync your reading position between devices, but only through a server. By default that is the public one at sync.koreader.rocks. cobiserver is a drop-in replacement: it implements the same endpoints the app already calls, so the only change on your e-reader is the server address in the sync settings.

The official protocol has no way to change a password or recover a lost one. cobiserver adds a small web interface for that:

  • Accounts at /account: register, change your password, set a recovery email, see which documents are synced.
  • Password recovery by email if SMTP is configured. If it isn't, the server prints a reset link for the admin to pass on.
  • Admin panel at /admin/users to create and delete users or force a reset without a shell. The first account registered becomes admin.
  • Admin CLI in the same binary: create-user, set-password, list-users, gen-reset-link and a few more.

Try it

git clone https://github.com/SecureCMD/cobiserver.git
cd cobiserver
docker compose up -d --build

That starts the server on port 8080. In KOReader, go to Settings → Sync, set the custom server to http://<your-host>:8080 and register from the app. Or open /account/register in a browser.

Without Docker, sudo make install on the target machine installs the binary and a sandboxed systemd unit. On Debian or Ubuntu, make deb builds a package that apt can install and remove cleanly.

How it is built

  • One static Go binary with pure-Go SQLite, no CGO. The Docker image is about 20 MB and runs as a non-root user.
  • Dependencies are vendored, so no build path touches the network.
  • The KOReader app sends MD5(password). The server stores that value through bcrypt, so a leaked database is not a list of logins.
  • Rate limiting on register, login, auth and password recovery.
  • make dist cross-compiles release archives for Linux amd64, arm64 and armv7, and macOS arm64, with checksums.

Known limits

  • The server speaks plain HTTP. For anything beyond your home network, put a reverse proxy with TLS in front of it and set COOKIE_SECURE=true.
  • Debian 12 ships Go 1.19, which is too old to build it. Install Go 1.23 or later first.