kosync-rs is a self-contained Rust replacement for koreader/koreader-sync-server. It keeps the KOReader sync API compatible while replacing the old Redis, OpenResty/nginx, Lua/Gin, and runit stack with one binary and one SQLite database.

Compatibility target:

Upstream checkout: ../koreader-sync-server
Upstream commit: 597e0648be0894c535a222f192d7bd583fb3b2dc
Target platforms: Linux amd64 and Linux aarch64

Quick start

docker compose up -d
curl -k -H "Accept: application/vnd.koreader.v1+json" https://127.0.0.1:7200/healthcheck

The compose file stores data in ./data/kosync.sqlite3, enables user registration, exposes HTTPS on 7200, and exposes plain HTTP on 17200 for reverse proxies.

The default compose file uses the published multi-arch image sodium/kosync-rs:v2.1.1, which supports Linux amd64 and aarch64.

Binary usage

kosync-rs serve
kosync-rs init-db --db ./data/kosync.sqlite3
kosync-rs healthcheck --url https://127.0.0.1:7200/healthcheck --insecure

Useful environment variables:

KOSYNC_DB=./data/kosync.sqlite3
KOSYNC_HTTP_ADDR=0.0.0.0:17200
KOSYNC_HTTPS_ADDR=0.0.0.0:7200
KOSYNC_TLS=auto
KOSYNC_TLS_CERT=/path/to/cert.pem
KOSYNC_TLS_KEY=/path/to/key.pem
ENABLE_USER_REGISTRATION=true
RUST_LOG=info

ENABLE_USER_REGISTRATION matches the old server: registration is enabled only when the value is exactly true or 1.

API

Implemented routes:

POST /users/create
GET  /users/auth
PUT  /syncs/progress
GET  /syncs/progress/:document
GET  /healthcheck

Authenticated routes use:

x-auth-user: <username>
x-auth-key: <client key>

The server stores and compares the auth key exactly as supplied, matching the original implementation.

Migrating from the old Docker container

Keep the old container running while importing. The old Redis usually listens on 127.0.0.1:6379 inside that container, so the helper script joins the old container's network namespace.

--sqlite may point to a SQLite database file or to a directory. When it points to a directory, the scripts use kosync.sqlite3 inside that directory.

scripts/import-from-old-redis.sh \
  --old-container kosync \
  --sqlite ./data/kosync.sqlite3 \
  --image sodium/kosync-rs:v2.1.1

Then stop the old container and start the new compose stack:

docker stop kosync
docker compose up -d

Export SQLite data back to the old Redis format:

scripts/export-to-old-redis.sh \
  --old-container kosync \
  --sqlite ./data/kosync.sqlite3 \
  --image sodium/kosync-rs:v2.1.1

The export script will not flush Redis unless --flush-target is passed.

Backups

SQLite backup:

sqlite3 ./data/kosync.sqlite3 ".backup './data/kosync-backup.sqlite3'"

Portable JSON backup:

kosync-rs export-json --db ./data/kosync.sqlite3 --output backup.json
kosync-rs import-json --db ./data/kosync.sqlite3 --input backup.json

License

This project is intended to be compatible with the AGPL-3.0 upstream server and is licensed as AGPL-3.0-or-later.