Skip to content

Liseur and Liseur-Sync

This is a tool reference

What a tool or project is, who makes it, and what it is for, whether someone else wrote it or I did. Everything I have learned about it lives elsewhere and links back here.

An open-source EPUB reader for Android paired with a self-hosted sync server, designed for reading-position synchronization across devices and integration with personal book libraries.

What it is

Liseur1 is the Android client: an EPUB reader using the Readium engine with support for local files, OPDS catalogs, and sync servers. Liseur-sync2 is the companion server: a single Go binary that provides reading-position synchronization, library management, and statistics.

Together they form a self-hosted alternative to commercial ebook ecosystems, with explicit support for KOReader synchronization and Calibre library integration.

Key capabilities

Reading synchronization

Reading positions are stored as an append-only log rather than replacing the previous state. This allows the server to resolve updates from multiple devices without older clients blindly overwriting newer state. The same history derives reading sessions and statistics.

Book identity is independent of filesystem path - clients resolve books using content and metadata identifiers before exchanging reading state. Reader preferences (typeface, theme, margins) sync as a small map of opaque strings per account, resolving by last-writer-wins.

Library management

The server can index either:

  • A directory containing EPUB files
  • A Calibre library using metadata.db

Folders are granted to accounts individually and are read-only by default. Uploads and deletions require explicit configuration via liseur-sync admin folder-uploads <folder-id> on.

Web reader with offline PWA

A browser-based EPUB reader is included, using the same synchronization API as native clients. When another device has read further, the reader offers to continue there, naming both pages and how long ago the other device was there.

The web UI ships as a PWA: choose "Save offline" for each book, install via "Add to Home Screen", and read without a network connection. Positions, highlights, notes, and reading sessions are stored locally until reconnection.

Interfaces

  • Native REST API
  • KOReader-compatible kosync API
  • OPDS 1.2 catalog
  • Per-user reading statistics and sessions
  • Per-user series claims
  • Browser-based administration interface

Installation

Quick install

curl -fsSL https://raw.githubusercontent.com/chmouel/liseur-sync/main/scripts/install.sh | bash

Docker Compose

SQLite (simplest):

docker compose --profile sqlite up -d

Bundled PostgreSQL:

docker compose --profile postgres up -d

External PostgreSQL:

docker compose --profile external up -d

Build from source

go build ./cmd/liseur-sync
./liseur-sync serve

Initial setup

The web interface is at /ui/. When the database contains no accounts, the setup page creates the initial administrator account and can watch a first folder of books in the same step.

Users, folders, API tokens, folder grants, and reader pairing are managed from the administration interface or with the admin CLI.

Client integration

Liseur uses the native API. Protocol and synchronization details are documented in docs/integrating.md in the server repository.

OpenAPI specification: docs/openapi.yaml

  • liseur-desktop: Desktop version (abandoned)
  • KOReader: Supported via kosync-compatible API
  • Calibre: Integration via metadata.db catalog

License

MIT

Author

Chmouel Boudjnah

The following pages link to this page:

  1. chmouel/liseur: EPUB reader for Android, last modified 2026-09-28 ↩

  2. chmouel/liseur-sync: sync server for Liseur, last modified 2026-09-28 ↩