Self-hosted ebook library Bookshelf runs on Cloudflare R2 or Node, no database

What Bookshelf is

Bookshelf is a self-hosted library for the ebooks you already own, released under the MIT licence and featured on the Hacker News front page. According to the project's GitHub repository, it provides a single server-rendered page that lists your collection, filters it with a search box, hands out downloads, and reads books directly in the browser — EPUB and PDF files each get their own dedicated reader. There is no database anywhere in the design: everything the application needs lives in the storage backend it is pointed at.

Two storage providers

The app ships with two interchangeable backends, and the README calls the storage-provider contract the project's main extension point: a package published by anyone can be installed and named in the config to add further options.

The first backend runs the whole application as a Cloudflare Worker with R2 object storage underneath, which means no container and no server to keep alive. Deploying requires a Cloudflare account and a wrangler login; the sync command creates the bucket and uploads the library, and a separate command pushes the Worker. Two checked-in configuration files carry the bucket and Worker names, and they have to agree — the tooling cross-checks them before anything uploads and reports a mismatch rather than deploying to an empty shelf.

The second backend is a Node server that reads from a folder on disk, suited to a laptop or a VPS. It requires Node 24 or newer on a Unix-like system, because the sync tool discovers its image utilities via which, which rules out Windows. Cover art comes out better when cwebp and pdftoppm are installed, and the Docker image bundles both, making it the shortest route: drop EPUBs into a books directory, run the sync step, and start the container to get a shelf on localhost port 3000. A single named volume holds the published books plus everything the app writes to them — profiles and reading positions — so nothing else requires a backup. The container runs as a non-root user, and bind-mounting a host directory means changing its ownership first.

Contributors are asked to run the lint, type-check and test commands before pushing; the test suite reaches the packages and the app's service layer, but not its pages.

A demo shelf out of the box

For anyone without books to hand, a demo command generates nine public-domain titles — eight EPUBs and one PDF, so both readers are immediately reachable. The titles and authors are genuine long-out-of-copyright works, while the text inside is placeholder; this is also how the repository's screenshots can be reproduced.

Running a public instance

The README is explicit that a library reachable by strangers should refuse to be modified. In that mode, storage continues to serve files but rejects every write: profiles cannot be added, renamed or deleted, and reading progress reverts to browser storage — the same fallback the app applies to any provider that cannot write. Switching between existing profiles still works, because that is a cookie rather than a change. Notably, the restriction is enforced at the storage layer rather than in the UI, so sending the affected requests directly receives the same refusal.

There is no authentication. Anyone who can reach the app can read and download the entire library and pick any profile, and the documentation frames profiles as a convenience for separating readers in the same household rather than access control. Two devices using one profile at the same time resolve as last-write-wins. The suggested mitigations are a network you trust or a gate in front of the app that authenticates callers.

Why it matters

Bookshelf shows how little infrastructure a personal media library actually needs: no database schema to maintain, no container on Cloudflare, and on the filesystem backend a single volume to back up. The documentation describes the library that the sync tool builds as regenerable, which keeps your books as the source of truth rather than an opaque store. The unusually frank security notes — stating plainly that there is no authentication and that public instances degrade to read-only — avoid overselling what the software does. The licence covers the code only; the copyright of the books you place in a library built with it remains between you and their publishers.