Calibre-Web

Calibre‑Web is a lightweight, Python‑based web front‑end that exposes a Calibre library through a modern HTML5 interface and an OPDS feed. At its core, the application parses a Calibre SQLite database to build an API‑driven catalog of eBooks and provides REST endpoints for searching, filtering, and metadata manipulation. The front‑end is served by a Flask application that leverages Jinja2 templates and Bootstrap 3 for responsive design. The codebase is intentionally modular: database access, authentication, and plugin hooks are isolated in separate packages, enabling developers to extend or replace components without touching the core.

• Language & Framework: Python 3.x with Flask as the web framework, SQLAlchemy for ORM‑like access to the Calibre SQLite file. The UI is rendered with Jinja2 and styled using Bootstrap 3, while JavaScript interactions rely on jQuery and custom scripts.
• Database: The only persistent store is the Calibre SQLite database (metadata.db), which contains all book metadata, custom columns, and user‑defined shelves. Calibre‑Web interacts with this file via a read‑only connection, ensuring compatibility with Calibre’s own command‑line tools.
• Authentication: The application supports multiple auth backends out of the box—local user tables, LDAP, Google/GitHub OAuth, and proxy headers. The auth layer is pluggable; developers can drop in a custom provider by implementing the auth.BaseAuth interface.
• Extensibility: A plugin system is exposed through a simple plugins directory. Each plugin registers hooks such as on_book_metadata_update, on_user_login, or opds_feed_customization. The plugin API is documented in the repository, and developers can ship plugins as separate Python packages that Calibre‑Web will load at runtime.
• Containerization: Official Docker images are available on Docker Hub (janeczku/calibre-web), built with a minimal Alpine + Python runtime. The Dockerfile mounts the Calibre library directory and exposes ports 8083 (HTTP) and 8443 (HTTPS). This setup allows developers to spin up isolated instances quickly or orchestrate multiple replicas behind a load balancer.

• OPDS Feed: Exposes a full OPDS 1.2 feed, automatically updated as the library changes. Developers can customize the feed structure via plugins or configuration flags (OPDS_ROOT, OPDS_ENABLE_SEARCH).
• Metadata API: REST endpoints for CRUD operations on book metadata, including custom columns. The API returns JSON and supports bulk updates via CSV import.
• Conversion Pipeline: Integrates with Calibre’s ebook-convert binary to perform on‑the‑fly format conversion. The conversion job queue is handled by Celery, allowing asynchronous processing and progress callbacks.
• User Permissions: Fine‑grained ACLs enable per‑user or per‑group restrictions on viewing, downloading, or editing books. Permissions are stored in the local SQLite user table and can be overridden by LDAP group mappings.

Running Calibre‑Web is straightforward on any Linux host with Python 3.6+. The application requires read access to the Calibre library folder and write permissions for temporary conversion files. For production deployments, it is recommended to:

• Use a reverse proxy (NGINX/Traefik) for HTTPS termination and URL routing.
• Deploy the app behind a WSGI server (Gunicorn) with multiple workers to handle concurrent users.
• Store the Calibre database on a dedicated SSD for fast query performance, especially when serving large libraries (10k+ books).
• Leverage Docker Compose or Kubernetes to manage replicas, persistent volumes, and environment variables (CALIBREWEB_DATABASE, CALIBREWEB_AUTH_METHOD).
  Scalability is bounded by the SQLite file: while single‑writer concurrency is safe, high read throughput can be achieved with a read replica or by migrating to a lightweight SQL server if needed.

• Plugins: The plugin API allows developers to add new authentication schemes, modify the OPDS feed, or inject custom UI components. Example plugins include a “Send to Kindle” feature and an “Audio Book Indexer.”
• Webhooks: Calibre‑Web can emit HTTP callbacks on events such as book addition, metadata update, or user login. These hooks enable integration with CI/CD pipelines, monitoring tools, or external notification services.
• Custom Columns: Calibre’s custom column feature is fully exposed; developers can create domain‑specific metadata (e.g., “Reading Level,” “Publisher Region”) and enforce visibility rules per user group.
• API Documentation: The REST API is documented in the repository’s docs/api.md and can be explored via Swagger UI when enabled (ENABLE_SWAGGER = True). This makes it straightforward to build client libraries in any language.

The codebase follows PEP‑8 conventions and is heavily commented, which lowers the learning curve for contributors. The README provides clear sections on configuration, plugin development, and troubleshooting. Community support is robust: a dedicated Discord channel hosts real‑time help, while the issue tracker encourages pull requests and feature discussions. Licensing under GPL v3 ensures that any modifications remain open source, fostering a collaborative ecosystem.

• Personal Library Server: A hobbyist can host their Calibre collection on a Raspberry Pi and access it from any