BeePub

BeePub is a self-hosted ebook library and reader for EPUB collections (TXT novels are converted to EPUB on upload). It can serve as a modern alternative to calibre-web, while also working as a standalone library for users who do not run Calibre. BeePub combines library management, a web reader, an iOS native app built with Capacitor, reading progress, highlights, tags, metadata tools, and optional AI-assisted features in one private deployment.

Try the live demo — one-click sign-in from the login page (demo / demodemo). Includes vertical (直排) Chinese classics to show off CJK rendering. Demo data resets every 6 hours.

Features

• Web reader with progress tracking, highlights, notes, table of contents, and mobile-friendly reading controls
• iOS native app support through Capacitor
• Offline reading for downloaded books
• Works with e-readers: OPDS catalog for browsing and downloading, plus KOReader progress sync (kosync-compatible)
• MCP server for AI assistants: let Claude (or any MCP client) search your library and full text, recap what you've read — spoiler-safe — and work with your highlights
• Automatic reading activity tracking, streaks
• Gacha-style random book pulls for choosing what to read next
• Metadata lookup from external book sources
• Optional AI features for tagging, summaries, companion chat, illustrations, semantic search, and similar-book recommendations
• PostgreSQL with pgvector for semantic search support

Quick Start

One file, one command — no required configuration. All services run from prebuilt multi-arch (amd64/arm64) images on GHCR; nothing is built locally.

mkdir beepub && cd beepub
curl -LO https://raw.githubusercontent.com/oalieno/beepub/main/docker-compose.yml
docker compose up -d

Open http://localhost and register — the first account automatically becomes the admin. A JWT secret is auto-generated on first start and persisted in the data volume; the database is only reachable inside the compose network.

Using Portainer, Synology Container Manager, or another compose UI? Paste docker-compose.yml as the stack definition — it references no other local files.

To customize (port, secrets, version pinning), download the example env file next to the compose file and uncomment what you need:

curl -Lo .env https://raw.githubusercontent.com/oalieno/beepub/main/.env.example

To pin a release instead of tracking latest, set BEEPUB_VERSION=0.1.0 in .env. To upgrade later:

docker compose pull && docker compose up -d

Building From Source

Clone the repository and add --build — every service also carries a build context, so the same compose file builds the images locally instead of pulling:

git clone https://github.com/oalieno/beepub.git && cd beepub
docker compose up -d --build

Importing A Calibre Library

Coming from calibre-web? Mount your Calibre library (the folder containing metadata.db) read-only into the backend and worker services — both have a commented-out line ready in docker-compose.yml:

    volumes:
      # ...existing volumes...
      - /path/to/calibre:/calibre:ro

Restart the stack, open Admin → Calibre in the app, and import the library it finds. Books are read in place from the mount — BeePub never writes to your Calibre library — and a periodic sync picks up books you add or change in Calibre later. To serve several libraries, mount each one as a subfolder of /calibre.

E-Readers: OPDS And KOReader Sync

Any OPDS client — KOReader, Readest, Foliate, Cantook, and most e-reader apps — can browse, search, and download your library:

Catalog URL:  https://<your-host>/opds
Credentials:  your BeePub username and password (HTTP Basic)

KOReader can also sync reading progress through BeePub. In KOReader open Tools → Progress sync → Custom sync server and set:

Server:       https://<your-host>/kosync
Username:     your BeePub username
Password:     your BeePub password

Progress syncs between KOReader devices with exact positions, and books matched to your library show the e-reader progress in BeePub too. Log in to the web UI once after upgrading to enable sync for accounts created on older versions. Book matching uses KOReader's default binary checksum method — download the book via OPDS so both sides have the same file.

AI Assistants: MCP

BeePub ships an MCP (Model Context Protocol) server, so AI assistants can work with your library: search books by fuzzy titles, keywords, or tags, find passages in the full text, read chapters, recap a book up to where you stopped, and pull your highlights and notes.

Create an API token under Profile → API Tokens, then connect a client — for example Claude Code:

claude mcp add --transport http beepub https://<your-host>/mcp \
  --header "Authorization: Bearer bpk_…"

Everything is read-only, scoped to the token's account and its library access. Chapter summaries are spoiler-protected on the server: the assistant only sees summaries up to your reading position unless you explicitly ask for the whole book.

Reverse Proxy

For a domain-based deployment behind Traefik, Caddy, nginx, or another reverse proxy, keep BACKEND_URL pointed at the internal Docker service and set SvelteKit's public origin for the frontend:

services:
  frontend:
    environment:
      ORIGIN: https://reader.example.com
      BACKEND_URL: http://backend:8000

BACKEND_URL is used only by the frontend server for internal server-side API calls. Browser requests still go through the public origin and nginx's /api proxy.

Configuration

The main deployment settings live in .env.

Important variables:

• POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD: PostgreSQL database settings; the database is not reachable from outside the compose network, so the defaults are safe to keep
• SECRET_KEY: JWT signing secret; auto-generated and persisted in the data volume when unset. Set it explicitly to control or rotate it — changing it logs every session out
• PORT: public nginx port
• CORS_ORIGINS: comma-separated public origins allowed to call the API; localhost browser origins on any port are always allowed
• LOG_FORMAT: console or json

API keys for optional AI and metadata providers are configured from the admin settings UI after setup.

Development

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

Run backend tests:

cd backend
uv run pytest

Run frontend checks:

cd frontend
pnpm format
pnpm check

Data And Backups

Docker Compose keeps runtime data in three named volumes:

• data: everything BeePub stores — books/ (uploaded books), covers/, illustrations/ (generated), and app/ (the auto-generated JWT secret)
• postgres_data: the database
• redis_data: Redis state (disposable)

Back up data and postgres_data before upgrading or rebuilding a production deployment.

To keep the data in directories of your own instead (a NAS share, say), set absolute host paths in .env:

BEEPUB_DATA_PATH=/srv/beepub/data
BEEPUB_POSTGRES_PATH=/srv/beepub/postgres

Upgrading from 0.13 or earlier: those versions kept books, covers, illustrations and the secret in four separate volumes (books_data, covers_data, illustrations_data, app_data). The migrate service moves their files into data on the first start, file by file — an interrupted move resumes on the next start, and it never needs twice the space. Once it has run, the old volumes are empty and can be removed. If you had pointed one of them at a host directory, it is left untouched: move its contents into the matching subdirectory of BEEPUB_DATA_PATH (e.g. books/) yourself.

The repository does not include book files, database contents, user data, API keys, or generated runtime assets.

License

BeePub is licensed under the GNU Affero General Public License v3.0 or later. See LICENSE.

The backend currently includes vendored EbookLib-derived code, which is licensed under AGPLv3-or-later. The frontend vendors foliate-js, which is MIT licensed (frontend/src/lib/reader/vendor/foliate/LICENSE).