bookshelf README

The project's README from github.com/murerkinn/bookshelf. As one markdown file: README.md.

Bookshelf

CI

A self-hosted library for the ebooks you already own. Put your EPUBs and PDFs in a folder, publish them, and read them in any browser — or on your Kobo, through the OPDS catalog.

The shelf: a searchable list of books with covers, a profile switcher, and a Continue button on the book being read

Run it as a Cloudflare Worker over R2, or as a Node server over a directory on your own machine. Both use the same code and the same library.

📖 Full documentation

Try it in a minute

You'll need Node 24 or newer and a Unix-like system. Windows isn't supported — the sync tool looks for its image tools with which.

git clone https://github.com/murerkinn/bookshelf.git
cd bookshelf
npm install
npm run demo

npm run demo writes nine generated public-domain books into books/ — eight EPUBs and a PDF, so both readers are one click away. It downloads nothing. Then publish and run them by whichever route below.

The checked-in bookshelf.config.json points at Cloudflare R2, so npm run sync goes there unless you change it. For a local look, switch it to the filesystem provider first:

// bookshelf.config.json
{ "storage": { "provider": "fs", "directory": "shelf-data" } }

Set up your own

Put your books in books/, then pick where the library should live.

With Docker

The shortest route, and the image ships the tools that make covers.

mkdir books && cp ~/Downloads/*.epub books/
docker compose run --rm sync --create
docker compose up -d

Your shelf is on http://localhost:3000. Sync flags pass through, so docker compose run --rm sync --force works as it does locally.

Back up the library volume — it holds your published books and your reading positions. To bind-mount a host directory instead, chown it first:

chown -R 1000:1000 /srv/bookshelf

On a machine you own

No account anywhere.

// bookshelf.config.json
{ "storage": { "provider": "fs", "directory": "shelf-data" } }

npm run sync -- --create
npm run build
npm start -w @bookshelf/app

More in the filesystem provider.

On Cloudflare

You'll need a Cloudflare account. Edit bookshelf.config.json and apps/bookshelf/wrangler.jsonc so they name your bucket and Worker — if they disagree, the sync tool stops before uploading.

npx wrangler login
npm run sync -- --create
npm run deploy

More in the R2 provider.

Before you commit a library to it

There is no authentication. Anyone who can reach your shelf can download every book in it, and pick any profile while doing it. The OPDS catalog makes it machine-enumerable as well. Put it on a network you trust, or behind something that asks who's calling.

Nothing is encrypted. Your library is stored in the clear, and object keys are slugified titles — a listing of your storage names your shelf. With the filesystem provider you can keep it on an encrypted volume today.

Two devices reading one profile at once is last-write-wins.

What's missing has the full list.

Configuration

variable what it does
BOOKSHELF_READ_ONLY set to 1 and storage keeps serving but stops accepting. Profiles can't be added, renamed or deleted, and reading positions stay in the browser. Set this on anything strangers can reach
BOOKSHELF_PROVIDER override the provider the build was made with
BOOKSHELF_DIRECTORY override where the filesystem provider looks
BOOKSHELF_SITE_URL the public address, for link previews and canonical URLs. Set it behind a proxy that doesn't say so

Everything else lives in bookshelf.config.json — see publishing.

Commands

All from the repository root.

npm run dev          # local dev server, against the local R2 bucket
npm run sync         # build the library and publish it
npm run build        # build every workspace
npm run check-types  # typecheck every workspace
npm run preview      # build + run the Worker locally
npm run deploy       # build + deploy to Cloudflare Workers
npm test             # the test suite
npm run lint         # biome, across the repo

npm run cf-typegen -w @bookshelf/app regenerates cloudflare-env.d.ts after you edit wrangler.jsonc.

Documentation

Published at https://murerkinn.github.io/bookshelf/.
Publishing a library the sync tool, its flags, and covers
The library format what ends up in storage, and what to back up
Storage providers choosing where your library lives
Cloudflare R2 setup, deploying, publishing locally
Filesystem your own machine or a VPS
Profiles who is reading, and where they got to
Reading in the browser the readers and their controls
The OPDS catalog reading on a Kobo, a Kindle, or any OPDS client
Architecture for working on the code
What's missing limitations, and what's planned

Contributing

See CONTRIBUTING.md. In short: Node 24, npm install, and npm run lint, npm run check-types and npm test before you push. Say what you verified — the tests reach the packages and the app's service layer but not its pages.

Storage providers are the extension point, and yours doesn't have to live here. A package published by anyone can be installed and named in the config.

License

MIT — see LICENSE.

That covers the code in this repository. The app and the Docker image also ship other people's, under their own terms, listed in THIRD-PARTY-NOTICES.md.

None of it says anything about the books you put in a library built with it, whose copyright is between you and their publishers.

bookshelf (murerkinn/bookshelf)

Searching Database…

373 ·GitHub
Bookshelf
What is this?Bookshelf is a self-hosted library for ebooks you already own. You put EPUBs and PDFs in a folder, publish them, and read them in a browser or on a Kobo via the OPDS catalog.
Does it need a database or a separate backend service?No. It runs purely on object storage: either as a Cloudflare Worker over R2, or as a Node server over a plain directory on your own machine, with no database at all.
How do I get it running?Clone it, run 'npm run demo' to generate sample books, then publish and run with Docker, a local filesystem setup, or deploy to Cloudflare by editing bookshelf.config.json and wrangler.jsonc to point at your R2 bucket and Worker.
What do I need installed before trying this?Node 24 or newer and a Unix-like system; Windows isn't supported because the sync tool shells out to image tools with 'which'. If you deploy to Cloudflare you'll also need a Cloudflare account for R2 and Workers.
Is it safe to just put my library online as-is?No — there's no authentication, so anyone who reaches your shelf can download every book and switch profiles, and nothing is encrypted; object keys are even slugified titles, so storage listings leak your book names.
Can I run this on my own machine or does it have to be Cloudflare?Both: run it locally or on a VPS as a Node server over a directory with the filesystem provider, or deploy it as a Cloudflare Worker backed by R2 — same code, same library either way.
Is my library data encrypted anywhere?No. The library is stored in the clear with no encryption, though the filesystem provider lets you put it on an encrypted volume yourself.
What's the OPDS catalog for?It exposes your library in a machine-readable catalog format so e-readers like a Kobo or Kindle can browse and download books directly, without a browser.
What happens if I read the same profile on two devices at once?Reading position syncing is last-write-wins, so simultaneous reading on two devices under one profile can overwrite each other's progress.
Can I lock the library down for public access?Yes, setting BOOKSHELFREADONLY to 1 keeps storage serving reads but blocks profile creation, renaming, deletion, and persisted reading positions — meant for shelves strangers can reach.
Is there a quick way to run it with Docker?Yes, the Docker image is the shortest route and already bundles the tools needed to generate covers, so you just mount your books and run it.
What are similar projects?calibre-web, grimmory, bookorbit, audiobookshelf, readest, Kavita, koreader, nodewarden
Which topics is it in?opds, ebook-reader, object-storage, epub, vps, cloudflare-workers, s3, serverless, ebook, backup, pdf, cloud
Creator
murerkinn
Size
1.3 MB
Stars
373
Updated
CommitAug 25
Age
2mo
Commits · 90 Days