Noureddine RAMDI / KoInsight: self-hosted KOReader analytics and sync server in one Docker container

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
948 Words
github-stars typescript docker koreader self-hosted dashboard sync-server

GeorgeSG/KoInsight

KoInsight pulls off a clever dual impersonation: it doubles as both a reading analytics dashboard and a drop-in replacement for KOReader’s official progress sync server. This means you can self-host your reading statistics visualization and synchronize your reading positions across devices without relying on KOReader’s default kosync service. All this runs inside a single Docker container, making deployment straightforward.

What KoInsight does and how it works

KoInsight is a self-hosted web application built primarily in TypeScript that visualizes KOReader reading statistics through interactive charts and insights. KOReader is an open-source e-reader software popular on devices like Kindle and PocketBook, which tracks reading habits and progress into a local SQLite database called statistics.sqlite.

The core functionality of KoInsight revolves around ingesting this statistics.sqlite file in two ways: either by manually uploading the file from a KOReader device or by an automated sync mechanism using a companion Lua plugin installed within KOReader itself. This plugin allows KoInsight to function as a full replacement for KOReader’s official progress sync server, known as kosync.

Architecturally, KoInsight serves two main roles:

  • Analytics dashboard: It processes and visualizes reading statistics data, presenting charts and insights about reading habits.
  • Sync server: It implements the kosync protocol sufficiently well that KOReader clients cannot distinguish it from the official sync server. This enables automatic cross-device synchronization of reading positions.

The application is configured via environment variables that specify the hostname, port, maximum upload size, and data storage path. It supports multi-device environments, allowing users to track reading progress on different KOReader installations.

An additional feature is the ability to manually add book covers per title through a UI component called the cover selector, which enhances the visualization experience.

What stands out technically and tradeoffs

KoInsight’s standout technical feature is its dual impersonation of KOReader’s sync server protocol alongside its analytics dashboard functionality. This is not trivial: the backend, written in TypeScript, must understand and respond correctly to kosync client requests, effectively acting as a transparent proxy or replacement server.

The tradeoff here is complexity in maintaining compatibility with KOReader’s evolving sync protocol. Since this is a reverse-engineered or independently implemented protocol, any changes in KOReader’s official kosync server might require updates to KoInsight.

The codebase is surprisingly clean and focused given its dual role. It uses environment variables for configuration rather than a large config file, which fits well with Docker deployment best practices but requires careful environment management.

For data ingestion, supporting both manual upload and automated syncing covers a wide range of user preferences and technical comfort levels. However, manual uploading can be cumbersome for some users, and automated syncing requires installing a Lua plugin on the KOReader device, which might be a barrier for less technical users.

The dashboard’s interactive charts provide real value for analyzing reading behavior, but the process to add book covers manually per title suggests that some aspects of user experience are still semi-manual and could be improved with automation in future iterations.

Overall, the code quality and architectural choices reflect a practical approach: using Docker Compose for deployment simplifies setup, and the dual role reduces the need to run separate services for analytics and syncing.

Quick start with Docker Compose

The project provides a straightforward Docker Compose snippet to get started quickly. Adding this to your compose.yaml file sets up the KoInsight service exposing port 3000 and mounting a local data directory:

name: koinsight
services:
  koinsight:
    image: ghcr.io/georgesg/koinsight:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data

After saving this file, simply run:

docker compose up -d

This spins up the application container. You can then access the web dashboard on http://localhost:3000 (or the configured hostname and port).

Configuration is managed through environment variables, which you can add to the Compose file or your environment to control hostname, port, upload size limits, and data storage paths.

Verdict

KoInsight is a practical tool for KOReader users who want to self-host their reading analytics while maintaining control over their reading progress sync. Its ability to act as both a dashboard and a sync server in one container is a neat engineering solution that reduces deployment complexity.

The main audience is technically inclined KOReader users or enthusiasts comfortable with Docker and willing to install a Lua plugin on their reading devices. For them, KoInsight offers richer insights into their reading habits than KOReader’s built-in stats and avoids reliance on the official sync service.

Limitations include the need to maintain compatibility with KOReader’s sync protocol and some manual steps like uploading the SQLite file or adding book covers manually. The project’s reliance on Docker and environment variables suits production or homelab environments but may deter casual users.

Overall, KoInsight delivers a focused, well-implemented solution worth exploring if you want more control and insight over your KOReader data without vendor lock-in or cloud dependencies.

→ GitHub Repo: GeorgeSG/KoInsight ⭐ 536 · TypeScript