BookLore

Self-Hosted

Your personal library, organized and synced across devices

Active(100)

5.4kstars

1views

Updated 1 day ago

Overview

Discover what makes BookLore powerful

BookLore is a **self‑hosted, full‑stack web application** designed to serve as a personal library management system for PDFs, EPUBs, comics, and other e‑book formats. From a developer’s standpoint it is an opinionated yet extensible platform that blends modern web technologies with robust backend services, enabling developers to host, customize, and integrate the application into larger ecosystems. The core goal is to provide a lightweight yet feature‑rich solution that can run on anything from a Raspberry Pi to an enterprise Kubernetes cluster while exposing clean APIs for automation and integration.

Dynamic Shelving & Smart Collections

Multi‑User & Permission Model

Metadata Harvesting

OPDS & API

Overview

BookLore is a self‑hosted, full‑stack web application designed to serve as a personal library management system for PDFs, EPUBs, comics, and other e‑book formats. From a developer’s standpoint it is an opinionated yet extensible platform that blends modern web technologies with robust backend services, enabling developers to host, customize, and integrate the application into larger ecosystems. The core goal is to provide a lightweight yet feature‑rich solution that can run on anything from a Raspberry Pi to an enterprise Kubernetes cluster while exposing clean APIs for automation and integration.

Key Features

Dynamic Shelving & Smart Collections – Rule‑based collections that auto‑update using SQL/NoSQL queries, enabling developers to build complex categorization logic without writing custom code.
Multi‑User & Permission Model – Role‑based access control (admin, librarian, reader) built on top of a PostgreSQL ACL system, with optional external OIDC support for SSO.
Metadata Harvesting – Background workers that query Goodreads, Amazon, Google Books, and Hardcover APIs to enrich book records; these can be swapped or extended via a plugin interface.
OPDS & API – A fully‑compliant OPDS 2.0 feed for reading apps, plus a RESTful JSON API (CRUD + search) that supports authentication via JWT or session cookies.
Import Pipelines – File‑watcher “BookDrop” for bulk ingestion, a CLI importer, and support for Kobo/KOReader sync hooks.
Built‑in Reader – A responsive Vue/React component that renders PDFs, EPUBs, and comics with theme support; the reader exposes an event bus for progress tracking.

Technical Stack & Architecture

Layer	Technology	Rationale
Frontend	Vue.js (or React) + Tailwind CSS	Component‑driven UI, fast rendering, easy theming
Backend	Go (Gin/Gonic) or Node.js (NestJS)	High concurrency, low memory footprint; both are used in forks for language preference
Database	PostgreSQL (primary) + Redis (cache & rate‑limit)	ACID guarantees for user data, Redis for quick metadata lookups
Background Jobs	Go routines or BullMQ (Redis)	Periodic metadata fetches, import pipelines
Containerization	Docker Compose / Helm chart	Immutable images, sidecar for OIDC providers
Deployment	Kubernetes (Helm), Docker Swarm, or bare‑metal	Supports autoscaling, rolling updates, and high availability

The application follows a micro‑service‑ish architecture even though it is shipped as a monolith. The API layer, background workers, and web UI are separate containers in the Docker images, allowing developers to scale each component independently. The database is exposed only via a secure internal network, and all external traffic passes through the API gateway which handles authentication and rate limiting.

Core Capabilities & Extensibility

Plugin System – A Go/JS plugin API that lets developers inject custom metadata scrapers, authentication backends, or UI widgets without modifying the core codebase.
Webhooks – Triggered on book addition, update, or deletion; ideal for syncing with external services (e.g., sending a notification to Slack).
GraphQL Endpoint – Optional, providing flexible querying for complex client use‑cases.
CLI Tools – booklore-cli exposes CRUD operations, bulk import, and status checks; useful for CI/CD pipelines.
SDKs – Official Go and JavaScript SDKs wrap the REST API, simplifying integration into custom dashboards or mobile apps.

Deployment & Infrastructure

BookLore’s Docker images are lightweight (~200 MB) and come pre‑configured for production use. A single docker-compose.yml can spin up the full stack, while a Helm chart allows deployment on Kubernetes with minimal effort. The application is stateless except for the PostgreSQL database, making it trivial to run behind a load balancer or in a multi‑node cluster. For developers looking for edge deployments, the image can be pushed to Cloud Run or AWS Fargate; the only requirement is persistent storage for the database and a read‑write volume for uploaded books.

Developer Experience

Configuration – Environment variables cover all knobs: database URL, OIDC endpoints, cache settings, and feature toggles.
Documentation – The README, API reference (Swagger/OpenAPI), and a developer guide cover setup, plugin creation, and deployment patterns.
Community – Active Discord channel, Open Collective backers, and regular releases ensure timely support.
Licensing – MIT license gives developers freedom to modify and redistribute the code, a significant advantage over proprietary DRM‑centric solutions.

Use Cases

Personal Library Server – A hobbyist can host BookLore on a home NAS, sync books from their Kobo or KOReader devices, and access the library via any browser.
Academic Repository – An institution can deploy BookLore to manage research PDFs, expose OPDS feeds to campus reading apps, and enforce fine‑grained access control.
Enterprise Knowledge Base – Companies can integrate BookLore with internal SSO (Authentik, Keycloak) and use webhooks to sync new policy documents into the system automatically.
Developer Tooling – CI