https://github.com/brunty/koreader-sync
📕 Yet another KOReader Sync server
https://github.com/brunty/koreader-sync
Last synced: 1 day ago
JSON representation
📕 Yet another KOReader Sync server
- Host: GitHub
- URL: https://github.com/brunty/koreader-sync
- Owner: Brunty
- License: lgpl-3.0
- Created: 2026-05-10T19:32:33.000Z (28 days ago)
- Default Branch: main
- Last Pushed: 2026-05-17T10:34:49.000Z (22 days ago)
- Last Synced: 2026-05-17T12:37:54.050Z (22 days ago)
- Language: Go
- Homepage:
- Size: 7.31 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# KOReader Sync
Yet another KOReader Sync server, written in Go for my own learning and experimentation.
API endpoints based on https://github.com/Open-Audiobook/koreader-sync-protocol
## Notes
This is the server part of koreader-sync, how things like document IDs are computed, and progress strings are calculated
are part of the client (e-reader device typically) communicating with this API. This API doesn't concern itself with
how they're formatted, it's just here to store them
## Hosting and running koreader-sync
An example `docker-compose.yml` setup:
```yaml
services:
koreader-sync:
image: brunty/koreader-sync:latest # Don't use latest, use a specific version
ports:
- "8080:8080"
environment:
- LOG_LEVEL=DEBUG # Debug puts a lot of info in the logs, not useful if you're not actively debugging something
volumes:
- data:/app/data # this is where the sqlite db file is stored
restart: unless-stopped
volumes:
data:
```
Then run `docker-compose up -d` and the server will be running at `http://localhost:8080` and the database will be
stored in the Docker volume
## Environment variables
All configuration is via environment variables. None are required - sensible defaults are used when they're not set.
| Variable | Possible values | Default | Description |
|------------------------|----------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------|
| `PORT` | Any valid TCP port number | `8080` | The port the HTTP server listens on. |
| `LOG_LEVEL` | `DEBUG`, `INFO`, `WARN`, `ERROR` | `WARN` | Minimum severity of log messages written to stderr. `DEBUG` is very verbose and only useful when actively debugging. Any unrecognised value falls back to `WARN`. |
| `DISABLE_REGISTRATION` | `true`, `false` (also `1`/`0`) | `false` | When truthy, new user registration is blocked and the register endpoint returns `403 Forbidden`. Useful for keeping the server private once your users are set up. |
## Connecting Your KOReader Device
1. Open a book (or document) in KOReader on your device.
2. Go to the progress sync settings (Settings > Progress Sync > Custom Sync Server) - enter your server URL
(http://localhost:8080 if it's running locally, or your own URL if behind something like a reverse proxy / tunnel)
3. Select "Register / Login" and enter your username and password (to set up your user the first time, select
"Register", for subsequence devices you can select "Login")
4. Select "Push progress from this device now" and progress will be sent and stored in koreader-sync
5. Set up automatic sync to your preferences ("Automatically keep documents in sync" and then configuring how often sync
is sent)
## Changing your password
If you need to change your password, there's a command line tool within the container:
`docker exec -it $containerID /bin/sh`
You can then use `./kor-cli` to call the `change-password` subcommand with a `-username` flag for the user you want to
change the password for. You'll be prompted to enter the new password by the terminal and it'll then save the new
password to that user
```
/app # ./kor-cli change-password -username myuser
Looking for user: myuser
Password: [you will type your new password here]
Updated password for myuser
```