koreader-sync

Python

Simple implementation of the KOReader position sync server for self-hosting at home which has docker support for arm and amd64 :)

Last updated Jun 2, 2026

Stars

Forks

Issues

Stars/day

Attention Score

View on GitHub ↗ Open in github.dev

Topics

#amd64 #arm #docker #koreader #koreader-sync #python #python3 #selfhosted

Language breakdown

Python 87.6%

Dockerfile 12.4%

▸ Files click to expand

README

Koreader position sync server

Description

This is a simple implementation of the KOReader (https://github.com/koreader/koreader) position sync server for self-hosting at home which has docker support for arm and amd64 :) This is a fork of https://github.com/myelsukov/koreader-sync but with a complete code rewrite.

Dependencies

FastAPI : https://github.com/tiangolo/fastapi
TinyDB: https://github.com/msiemens/tinydb
Uvicorn: https://www.uvicorn.org/
Python-dotenv: https://saurabh-kumar.com/python-dotenv/

Install and run

> pip install -r requirements.txt

> uvicorn kosync:app --host 0.0.0.0 --port 8081

Or via Docker

> docker build --rm=true --tag=kosync:latest .
> docker compose up -d

Environment Variables

RECEIVERANDOMDEVICE_ID ("True"|"False")

Set it true to retrieve always a random device id to force a progress sync. This is usefull if you only sync your progress from one device and usually delete the *.sdr files with some cleaning tools.

OPEN_REGISTRATIONS ("True"|"False")

Enable/disable new registrations to the server. Useful if you want to run a private server for a few users, although it doesn't necessarily improve security by itself. Set to True (enabled) by default.

Dockerhub

There is also a dockerhub image available if you are not able to build yourself the image.

For linux/amd64 you can use docker pull b1n4ryj4n/koreader-sync and for linux/arm docker pull b1n4ryj4n/koreader-sync:arm

Connection

Use http://IP:8081 as custom sync server
Recommendation: Setup a reverse proxy for example with Nginx Proxy Manager (https://nginxproxymanager.com/) to connect with https