132 lines
3.3 KiB
Markdown
132 lines
3.3 KiB
Markdown
# kosync-rs
|
|
|
|
`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
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
POST /users/create
|
|
GET /users/auth
|
|
PUT /syncs/progress
|
|
GET /syncs/progress/:document
|
|
GET /healthcheck
|
|
```
|
|
|
|
Authenticated routes use:
|
|
|
|
```text
|
|
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.
|
|
|
|
When run as root, the scripts chown the SQLite directory and existing database
|
|
file to UID/GID `10001`, matching the published image's `kosync` user. Override
|
|
with `KOSYNC_UID` and `KOSYNC_GID` only if you run the container with a different
|
|
runtime user.
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
docker stop kosync
|
|
docker compose up -d
|
|
```
|
|
|
|
Export SQLite data back to the old Redis format:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
sqlite3 ./data/kosync.sqlite3 ".backup './data/kosync-backup.sqlite3'"
|
|
```
|
|
|
|
Portable JSON backup:
|
|
|
|
```sh
|
|
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.
|