Self-host your reading stack with a clean web library, KOReader sync, and provider-powered book imports.

• 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

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.

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

• 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
• Searchable highlights and annotations hub with inline note editing and Markdown/JSON export
• 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
• Progressive Web App for easier access
• OPDS and WebDav Support

OPDS and WebDAV endpoints use HTTP Basic authentication. By default, your normal account password works there. In Settings -> Account, you can optionally set a separate Basic-auth password for those routes while keeping your normal account password valid too.

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/.

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

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.

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.

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

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

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

• VITE_ALLOWED_HOSTS - comma-separated host overrides for Vite/dev setups
• ACTIVATED_PROVIDERS - comma-separated search providers
• ZLIBRARY_BASE_URL - optional Z-Library upstream URL; use this when the default upstream is unavailable
• ACTIVATED_METADATA_PROVIDERS - comma-separated metadata providers, for example googlebooks,openlibrary,hardcover
• GOOGLE_BOOKS_API_KEY - optional Google Books key for higher rate limits
• HARDCOVER_API_TOKEN - optional server-wide token required for the Hardcover metadata provider
• METADATA_PROVIDER_TIMEOUT_MS - optional metadata provider timeout in milliseconds
• 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. If ACTIVATED_METADATA_PROVIDERS is unset, blank, or contains no valid values, on-demand metadata lookup stays disabled and the metadata update UI remains hidden.

Metadata provider notes:

• googlebooks works without a key; GOOGLE_BOOKS_API_KEY only improves rate limits.
• openlibrary works without a key.
• hardcover is skipped unless HARDCOVER_API_TOKEN is set.

Accepted provider names:

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

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
ACTIVATED_METADATA_PROVIDERS=googlebooks,openlibrary
GOOGLE_BOOKS_API_KEY=
HARDCOVER_API_TOKEN=
METADATA_PROVIDER_TIMEOUT_MS=
VITE_ALLOWED_HOSTS=
BODY_SIZE_LIMIT=Infinity

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
ACTIVATED_METADATA_PROVIDERS=googlebooks,openlibrary
GOOGLE_BOOKS_API_KEY=
HARDCOVER_API_TOKEN=
METADATA_PROVIDER_TIMEOUT_MS=
VITE_ALLOWED_HOSTS=
BODY_SIZE_LIMIT=Infinity

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.

The TypeScript test suite runs with bun test. The KOReader reader interoperability test runs separately because it needs KOReader's Linux LuaJIT runtime:

cd sake
bun run test:reader:interop

The command downloads and verifies the pinned KOReader v2026.03 Linux release, generates the deterministic EPUB and sidecar fixtures, and runs tests/reader/koreader-xpointer-interop-spec.lua headlessly. It runs natively on Linux x86_64 or arm64; on macOS it uses Docker when available. GitHub Actions runs it in the koreader-reader-interop job.

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.

• 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 is provider-based and routed through POST /api/search.

• anna, openlibrary, and gutenberg work as normal providers once enabled in ACTIVATED_PROVIDERS
• zlibrary also requires you to connect your Z-Library session in Settings -> Integrations

To enable Z-Library support, add it to ACTIVATED_PROVIDERS:

ACTIVATED_PROVIDERS=zlib,anna,openlib,gutenberg
ZLIBRARY_BASE_URL=

Z-Library mirror URLs must use HTTPS. Sake accepts up to five mirrors, with a maximum of 2,048 characters per URL.

In the app UI, open Settings -> Integrations, then use Connect Z-Library and either:

• log in with your email and password, or
• copy remix_userid and remix_userkey from your Z-Library cookies

The app uses those session values for authenticated Z-Library requests.

Run these from sake/:

bun run dev
bun run build
bun run preview
bun run check
bun run test
bun run db:generate
bun run db:migrate
bun run db:status

From the repository root, these compose entry points are available:

• docker-compose.yaml for a managed source build
• docker-compose.selfhost.yaml for a self-hosted source build
• docker-examples/docker-compose.prebuilt.yaml for a managed prebuilt image
• docker-examples/docker-compose.prebuilt.selfhost.yaml for a self-hosted prebuilt image

This repository is licensed under AGPL-3.0-only. See LICENSE for the full text.