# Project pack: Calibre-Web @ 6e840ac Facts about **Calibre-Web** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and 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. ## Version and source - Repository: https://github.com/janeczku/calibre-web - Pinned commit: `6e840acbda8d62fdd159bf3855c01872d629a914`. Use exactly this version. - Get it: `git clone https://github.com/janeczku/calibre-web calibre-web && cd calibre-web && git checkout 6e840acbda8d62fdd159bf3855c01872d629a914` - Or download a zip: https://github.com/janeczku/calibre-web/archive/6e840acbda8d62fdd159bf3855c01872d629a914.zip - 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. ## Running it - Easiest: ```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. ``` - Needs: 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 Read these in the repository before changing code: `CONTRIBUTING.md`. ## Customisation points (settings → extend → code) - **ui-settings** [settings]: Choose the light "standard" or dark "caliBlur" theme, the site title, books per page and which sidebar sections show. → `Admin → Edit UI Configuration (cps/config_sql.py config_theme, config_books_per_page, config_random_books…)` - **users-and-permissions** [settings]: Per-person accounts and rights (download, upload, edit, delete), and hiding books by tag or custom column, e.g. for children. → `Admin → users (cps/admin.py, cps/themes/standard/templates/user_edit.html)` - **features-on-off** [settings]: Turn uploads, guest browsing, self-registration, magic-link login and Kobo sync on or off. → `Admin → Edit Basic Configuration → Feature Configuration (uploads, anonymous browsing, public registration, Kobo sync)` - **send-to-ereader** [settings]: Set up email so "Send to Kindle" works; each user sets their e-reader address in their profile. → `Admin → Edit Email Server Settings (cps/themes/standard/templates/email_edit.html)` - **opds-and-kobo** [extend]: Browse and download from reading apps such as KOReader, Moon+ Reader or Marvin, or sync shelves to a Kobo. → `OPDS catalogue at /opds (cps/opds.py); Kobo sync (cps/kobo.py)` - **metadata-providers** [extend]: Add or change where book details and covers are fetched from. → `cps/metadata_provider/ (one Python file per source, e.g. google.py)` - **templates-and-css** [code]: Change the look and layout of any page, such as bigger covers or a simpler book page. → `cps/themes/standard/templates/*.html (pages), cps/static/css/style.css and caliBlur.css, cps/static/js/` - **routes** [code]: New pages or behaviour, such as a "what the kids are reading" page. → `cps/web.py (browsing and reading), cps/shelf.py, cps/editbooks.py, cps/admin.py` ## Must keep working - The Calibre library and metadata.db. Desktop Calibre must still open the library after any change. - Per-user permissions and content restrictions (hidden tags or columns must stay hidden). - OPDS (/opds) and Kobo sync, which e-readers and reading apps depend on. - Both themes (standard and caliBlur) should keep working if you change shared templates. ## Staying updatable The admin pages cover themes, users, restrictions, email and sync without a fork. Upstream welcomes pull requests but won't add more login methods, file storages, social features, payments or analytics (see CONTRIBUTING.md). Larger enhancements go to the development branch; keep purely personal changes in your own copy. ## Data, costs and safety - 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. Back up both the Calibre library folder and the config folder. Calibre-Web edits metadata.db when you upload or edit books, so don't edit the same library in desktop Calibre at the same moment. - Service: Email (SMTP or Gmail) (optional, free with most providers): Send books to Kindle and other e-readers by email, and send password resets. - Service: Book metadata sources (Google Books, Amazon, ComicVine, Douban, Lubimyczytac, Google Scholar) (optional, free): Fill in missing titles, descriptions and covers. Book titles and authors are sent to the chosen source. - Service: Kobo store proxy (optional, free): Kobo sync can pass store requests through to Kobo so the device's shop still works. - Service: Google Drive (optional, free): Keep the Calibre library on Google Drive instead of a local disk. - Service: Login providers (LDAP, GitHub or Google OAuth, reverse-proxy login) (optional, free): Log in with an existing account. - Setting `PUID`: LinuxServer image only. The user id that owns your book folders, so the app can read and write them. - Setting `PGID`: LinuxServer image only. The group id that owns your book folders. - Setting `TZ`: Your time zone, e.g. Europe/London. - Setting `DOCKER_MODS`: LinuxServer image only. Set to linuxserver/mods:universal-calibre to add Calibre's converter (x64 only). - Setting `CALIBRE_DBPATH`: Folder where Calibre-Web keeps its own settings database (app.db). Not the book library. - Setting `CALIBRE_PORT`: Port to listen on (default 8083). - Setting `SECRET_KEY` (**secret**: the person enters it themselves, never in chat): Session signing key. If unset, one is generated and stored in app.db. - Change the default admin / admin123 password at first login. - Leave public registration and anonymous browsing off unless you really want strangers in. Use HTTPS if it's on the internet. - Many ebooks are copyrighted. Sharing your library with people outside your household may break the law. - The OPDS feed and Kobo sync URLs give access to books. Treat Kobo sync links like passwords. --- # Customising Calibre-Web Calibre-Web is a mature Flask app with no front-end build step. **Almost everything a household needs is in the Admin pages.** Use levels 1 and 2 first. ## Level 1: Settings (no code) All of these are in the web interface, under **Admin**: - **Look:** *Edit UI Configuration*. - *Theme:* light "standard" or dark "caliBlur". - *Title* of the site, *Books per Page* and random books. - Which sections show in the sidebar for new users. - **Features:** *Edit Basic Configuration → Feature Configuration*. Turn on *Enable Uploads*, *Enable Anonymous Browsing*, *Enable Public Registration*, *Enable Magic Link Remote Login* and *Enable Kobo sync*. - **People:** *Edit Users*. - Rights per person: download, upload, edit, delete, admin. - Hide or allow books by tag or custom column, e.g. a child only sees books tagged "Children". - **Send to e-reader:** *Edit Email Server Settings* (SMTP or Gmail). Each person adds their Kindle or e-reader email in their own profile. - **Scheduled tasks:** *Edit Scheduled Tasks Settings* for overnight thumbnail generation and similar jobs. - **Language:** each user picks their interface language in their profile (20+ languages). ## Level 2: Extend (no fork) - **OPDS catalogue** at `/opds` (`cps/opds.py`). Reading apps such as KOReader, Moon+ Reader or Marvin can browse and download books. - **Kobo sync** (`cps/kobo.py`). Shelves sync to a Kobo, with reading progress. Needs `kepubify` for the best results. - **Metadata sources** in `cps/metadata_provider/`. One Python file per source (Google, Amazon, ComicVine…). Add a file to add a source. - **Desktop Calibre** works on the same library for heavy editing, conversion and plugins. Don't use both on the library at the same moment. ## Level 3: Code Read upstream `CONTRIBUTING.md` first. | Change | Where | |---|---| | Page layout | `cps/themes/standard/templates/*.html` (e.g. `index.html`, `detail.html`, `layout.html`) | | Dark theme differences | `cps/themes/caliblur/templates/` overrides, `cps/static/css/caliBlur.css` | | Styles | `cps/static/css/style.css` | | Browser behaviour | `cps/static/js/` (e.g. `main.js`, `details.js`) | | Browsing, reading and search pages | `cps/web.py`, `cps/search.py` | | Shelves | `cps/shelf.py` | | Book editing and upload | `cps/editbooks.py`, `cps/uploader.py` | | Admin settings | `cps/admin.py`, `cps/config_sql.py` | | Text | wrap strings in `_()`; translations are in `cps/translations/` (`messages.pot` at the root) | ## Running locally - **Just use it (Docker):** 1. Run the LinuxServer image recommended in the README: `docker run -d -p 8083:8083 -e PUID=1000 -e PGID=1000 -v ./config:/config -v /path/to/library:/books lscr.io/linuxserver/calibre-web:latest` 2. Open http://localhost:8083 and log in as admin / admin123. 3. Set the database folder to `/books`. 4. Change the password. - **Just use it (pip):** `python3 -m venv cw && cw/bin/pip install calibreweb && cw/bin/cps` - **Develop:** 1. In a clone, run `python3 -m venv venv && ./venv/bin/pip install -r requirements.txt` (add `optional-requirements.txt` for extras). 2. Start it with `./venv/bin/python cps.py`. 3. Use a *copy* of your library while you experiment. - **Check:** - There is no automated test suite in this repo (upstream's tests live in a separate project). Click through the pages you changed in both themes. - Run ESLint on JavaScript changes (config in `.eslintrc`). ## Pitfalls - Never experiment on your only copy of the library. `metadata.db` is changed by uploads and edits. - Templates are shared by both themes. caliBlur overrides some of them, so check the dark theme too. - Kobo sync and OPDS have their own login rules. Test them with a real device or app after changes. - The LinuxServer Docker image is maintained by another team. Image problems go to their repository, not Calibre-Web's. --- Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/calibre-web/6e840ac/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/calibre-web/6e840ac/SKILL.md)