# Project pack: Calibre-Web @ 6e840ac

Facts about **Calibre-Web** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> Calibre-Web puts your collection of ebooks on a friendly web page. Browse by cover, author or series, read in the browser, and send a book to your Kindle or sync it to a Kobo with one click. Each family member can have their own login, shelves and reading list. It works with a library made by Calibre, the popular free ebook program.

## Setup path (checked 2026-11-03)
- **Start here, no Docker:** Install it with its language package manager. No Docker.
- Offer Docker only if the person asks or this path fails. The commands further down may use Docker; they are not the starting point.
- Verdict source: https://raw.githubusercontent.com/janeczku/calibre-web/HEAD/README.md
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/janeczku/calibre-web
- Pinned commit: `6e840acbda8d62fdd159bf3855c01872d629a914`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/janeczku/calibre-web/archive/6e840acbda8d62fdd159bf3855c01872d629a914.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://github.com/janeczku/calibre-web/wiki
- Licence: **GPL-3.0-or-later**. Free to use and change. If you give copies of the program (changed or not) to other people, you must share the source code under the same licence. Running it for your household, or as a website others use, has no extra obligations.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/janeczku/calibre-web bespoke-calibre-web
  cd bespoke-calibre-web
  git checkout --detach 6e840acbda8d62fdd159bf3855c01872d629a914
  # Prepare development requirements and local configuration first.
  # Setup notes: http://localhost:8083
  python3 -m venv venv && ./venv/bin/pip install -r requirements.txt && ./venv/bin/python cps.py
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  docker run -d --name calibre-web -e PUID=1000 -e PGID=1000 -e TZ=Europe/London -p 8083:8083 -v ./calibre-web-config:/config -v /path/to/your/calibre/library:/books lscr.io/linuxserver/calibre-web:latest
  # open http://localhost:8083, log in as admin / admin123, set the database folder to /books and change the password.
  # No Calibre library yet? Put the sample library/metadata.db from the repo in the books folder.
  ```
- Tools these commands use: Docker (the community LinuxServer image recommended in the README), or Python 3.8+ with pip, A Calibre library (a folder with metadata.db), Optional: Calibre's ebook-convert for format conversion, kepubify for Kobo, ImageMagick for covers
- Develop: `python3 -m venv venv && ./venv/bin/pip install -r requirements.txt && ./venv/bin/python cps.py   # http://localhost:8083`
- Check/lint: `npx eslint cps/static/js   # uses the .eslintrc in the repo root`
- Stack: python, javascript, html (Flask, SQLAlchemy, Jinja2, Tornado, Bootstrap 3, jQuery). Difficulty for a non-developer with an AI: **moderate**. A mature Flask app with no front-end build step: pages are Jinja templates in cps/themes/standard/templates/ with plain JavaScript and CSS in cps/static/. Most settings are in the admin pages. The Python modules are long and there is no automated test suite in the repo (tests live in a separate project), so check changes by hand.
- The project's own AI instructions, in the repository: `CONTRIBUTING.md`.
Personal data: **yes**. Stored in: Your books and Calibre's metadata.db stay in your Calibre library folder. Users, shelves, reading status and settings are in Calibre-Web's own app.db in the config folder. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/calibre-web/6e840ac/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/calibre-web/6e840ac/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/calibre-web/6e840ac/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/calibre-web/6e840ac/r3/SKILL.md)