Sake

<p align="center"> <img src="./sake/static/icons/sake-icon.svg" alt="Sake logo" width="120" height="120" /> </p> <h1 align="center">Sake</h1> <p align="center"> Self-host your reading stack with a clean web library, KOReader sync, and provider-powered book imports. </p>

Table of contents

• Why Sake?
• Quick start
• Features
• What lives in this repo?
• Choose a setup
• Configuration
• First boot
• KOReader plugin
• Search providers and downloads
• Useful commands
• Screenshots
• License

Why Sake?

If you already use KOReader, Sake gives you a much nicer home base around it. You get a self-hosted web library, seamless progress sync, note-aware reading updates, easy book delivery to devices, and a built-in plugin update flow without losing the KOReader setup you already like.

Quick start

For the fastest fully self-hosted setup, use the prebuilt Docker image and the bundled self-host compose file from the repository root:

docker compose -f docker-examples/docker-compose.prebuilt.selfhost.yaml up

Then open http://localhost:5173.

This setup gives you:

• the published ghcr.io/sudashiii/sake image
• a file-backed libSQL database
• SeaweedFS as S3-compatible storage
• automatic database migrations before the app starts

Features

• Personal library management with covers, metadata, shelves, ratings, and reading state
• Comprehensive reading stats for your library and reading habits
• Rule-based shelves to automatically organize your collection
• Directly download books from multiple provider-based search sources into your collection
• KOReader device pairing and sync from the same self-hosted stack
• Seamless background reading progress sync across devices, including notes and sidecar metadata
• Export an existing KOReader device library back into the web app
• Built-in KOReader plugin updater and release delivery
• Flexible deployment with Docker images or local Bun development
• libSQL plus S3-compatible storage support for managed or fully self-hosted setups

What lives in this repo?

This repository has three important layers:

• sake/ - the actual SvelteKit app (Svelte 5 + SvelteKit + Bun)
• koreaderPlugins/ - the KOReader plugin shipped by the app
• docs/ - shared project documentation and screenshots

If you are working on the app itself, run app commands from sake/.

Choose a setup

1. Self-hosted reference stack

Use this if you want the easiest all-in-one setup for local or personal self-hosting.

It uses:

• docker-examples/docker-compose.prebuilt.selfhost.yaml for the published image path
• docker-compose.selfhost.yaml at the repository root
• sake/.env.docker.selfhosted
• a file-backed libSQL database
• SeaweedFS as the S3-compatible storage example
• a one-shot migrator container that applies schema changes before the app starts

From the repository root with the prebuilt image:

docker compose -f docker-examples/docker-compose.prebuilt.selfhost.yaml up

Or build it locally from source:

docker compose -f docker-compose.selfhost.yaml up --build

Then open http://localhost:5173.

Data is persisted under:

• ./.data/selfhost/libsql
• ./.data/selfhost/seaweedfs

2. Docker app container with external database/storage

Use this if you want to run only the Sake containers but keep your database and object storage elsewhere, for example:

• Turso for libSQL
• Cloudflare R2 or another S3-compatible storage provider

Edit sake/.env, then start from the repository root with the prebuilt image:

docker compose -f docker-examples/docker-compose.prebuilt.yaml up

Or build it locally from source:

docker compose up --build

This Compose stack runs:

• sake-migrator first (bun run db:migrate)
• sake after the migration succeeds

Then open http://localhost:5173.

3. Local Bun development without Docker

Use this if you are developing the app locally and already have a reachable database and S3-compatible storage.

Configure sake/.env, then run from sake/:

bun install
bun run db:migrate
bun run dev

Then open http://localhost:5173.

If you are not using Docker Compose, run bun run db:migrate before first boot and again after future schema changes.

4. Pin a prebuilt image version

Published images live at ghcr.io/sudashiii/sake.

Available tags:

• latest
• <version> where <version> matches the existing CalVer without the webapp/v prefix
• sha-<shortsha>

Example:

SAKE_IMAGE=ghcr.io/sudashiii/sake:2026.03.28.1 docker compose -f docker-examples/docker-compose.prebuilt.yaml up

Configuration

Copy sake/.env.example to sake/.env and fill in the values you need.

Required groups

• LIBSQL_* - database connection
• S3_* - S3-compatible object storage connection

Optional values

• VITE_ALLOWED_HOSTS - comma-separated host overrides for Vite/dev setups
• ACTIVATED_PROVIDERS - comma-separated search providers
• BODY_SIZE_LIMIT - upload/body size limit

If ACTIVATED_PROVIDERS is unset, blank, or contains no valid values, search stays disabled and the search UI remains hidden.

Accepted provider names:

• anna, annas, annas-archive, or annasarchive
• openlib or openlibrary
• gutenberg
• zlib or zlibrary

Example: managed infrastructure

LIBSQL_URL=libsql://your-database-name.turso.io
LIBSQL_AUTH_TOKEN=your-turso-auth-token

S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
S3_REGION=auto
S3_BUCKET=your-bucket-name
S3_ACCESS_KEY_ID=your-access-key-id
S3_SECRET_ACCESS_KEY=your-secret-access-key
S3_FORCE_PATH_STYLE=false

ACTIVATED_PROVIDERS=anna,openlib,gutenberg
VITE_ALLOWED_HOSTS=
BODY_SIZE_LIMIT=Infinity

Example: fully self-hosted

LIBSQL_URL=file:./sake-selfhosted.db
LIBSQL_AUTH_TOKEN=

S3_ENDPOINT=http://localhost:8333
S3_REGION=us-east-1
S3_BUCKET=sake
S3_ACCESS_KEY_ID=sakeadmin
S3_SECRET_ACCESS_KEY=sakeadminsecret
S3_FORCE_PATH_STYLE=true

ACTIVATED_PROVIDERS=anna,openlib,gutenberg
VITE_ALLOWED_HOSTS=
BODY_SIZE_LIMIT=Infinity

First boot

If the database is empty, Sake exposes the normal bootstrap flow in the UI so you can create the first account there. You do not need to predefine a user in the environment.

KOReader plugin

The KOReader plugin lives in koreaderPlugins/sake.koplugin.

Basic setup flow:

1. Install the plugin in KOReader like any other plugin.
2. Open Settings -> More tools -> Sake.
3. Open Setup.
4. Set the public URL of your Sake web app in Server URL.
5. Optionally rename the device in Device Name.
6. Choose Pair Device and log in with the same username and password you use in the web app.
7. Use the actions in Sync, Library Import/Export, and Maintenance as needed.

The login step exchanges your password for a device API key and clears the password from the device afterward.

You can also export ebooks from the devices home folder back to the web app, including sidecar data such as progress and notes. Great if you have a pre-existing library on your device!

KOReader plugin releases are tracked in the database and the artifacts are served through S3-compatible storage. If the KOReader plugin is updated and you start the app, the new version will be uploaded to S3 so you can use the updater plugin to easily update the core plugin without needing to manually move the files to your KOReader device.

Concrete Usage

• The Plugin can be found under "Settings" --> "More tools" --> "Sake"
• Setup contains Server URL, Device Name, and Pair Device / Refresh Device Key
• Sync contains Download New Books, Pull Progress From Other Devices, and Upload Current Book Progress
• Books are downloaded when pressing Download New Books or when setting the device to sleep
• Progress is automatically uploaded when putting the device to sleep while a book is still open
• If you use multiple devices, use Pull Progress From Other Devices to fetch newer progress from another reader
• Library Import/Export -> Import or Export Existing Library uploads books already on the device, along with sidecar data such as progress and notes
• Library import/export can take a while, and the device may be unusable until the process finishes
• Maintenance -> Check for Plugin Updates checks for new plugin releases
• Maintenance -> Advanced -> Remote Log Shipping toggles shipping KOReader logs back to Sake
• Before using the plugin you need to set the server URL and pair the device. Your password is removed from the device after pairing succeeds.
• You can optionally change the auto-generated device name. The device name shows up in the web app for device-specific downloads and API keys.

Search provider