fix(calibre-web): document the optional features, drop the dead calibre install (#3032)

* feat(calibre-web): document the optional features and drop the dead calibre install

Issue #1143 asks how to add Calibre-Web's optional extras (metadata, kobo,
...) to the add-on. They are already there: the LinuxServer base image pip
installs optional-requirements.txt alongside requirements.txt into its
/lsiopy virtualenv, so every extra ships enabled. Listing the .dist-info
directories of the published image confirms scholarly, rarfile, py7zr,
mutagen, jsonschema, python-ldap, flask-dance, PyDrive2, comicapi and the
rest are present. Running pip install calibreweb[...] in the container just
fetches an unused second copy from PyPI and is thrown away when the
Supervisor recreates the container.

What actually hides the reporter's cover fields is Calibre-Web's own
gating: book_edit.html only renders 'Fetch Cover from URL' and 'Upload
Cover from Local Disk' when current_user.role_upload() and g.allow_upload
are both true, i.e. Enable Uploads plus the user's Upload permission. The
README now says so.

While checking where the Calibre binaries come from, the Dockerfile step
that claimed to install them turned out to be dead. The image has no wget,
only curl, so 'wget ... | sh /dev/stdin install_dir=/opt/calibre' loses
wget to exit 127, hands sh an empty script, and the pipeline still exits 0.
In the published amd64 image that RUN's layer decompresses to an empty tar
and no layer contains anything under /opt/calibre. Repairing it with curl
would not help: calibre's installer then hard-exits on the missing libEGL,
libOpenGL and libxcb-cursor that the universal-calibre mod apt-installs
itself, so the build would start failing and the image would grow by about
a gigabyte for binaries the mod already provides at start. The step is
removed and a comment records where the binaries really come from.

Refs https://github.com/alexbelgium/hassio-addons/issues/1143

* docs(calibre-web): tighten the optional-features wording after review

Say pip install calibreweb[...] is unsupported and can disturb the pinned
dependencies rather than calling the result unused, scope the extra-package
advice to compatible packages, list the calibre binaries as examples rather
than as a set all three operations need, and mark the docker mod as the
default rather than a certainty since DOCKER_MODS can be overridden.

calibre_web/CHANGELOG.md

@@ -1,4 +1,8 @@
  
+## 0.6.27.3 (2026-08-30)
+- Doc: explain in the README that Calibre-Web's optional extras (metadata, kobo, gdrive, gmail, goodreads, ldap, oauth, comics) are already installed by the LinuxServer base image, that `pip install calibreweb[...]` inside the container is useless and not persistent, and that the cover fields on the Edit Metadata page are gated on `Enable Uploads` plus the user's `Upload` permission (https://github.com/alexbelgium/hassio-addons/issues/1143)
+- Fix: remove the Dockerfile step that claimed to install the Calibre binaries into `/opt/calibre`. There is no `wget` in the image, so the command failed silently and left the layer empty; the binaries are and were provided at start by the default `linuxserver/mods:universal-calibre` docker mod
+
 ## 0.6.27.2 (2026-08-23)
 - Fix: trust the whole supervisor network range for the ingress auth header instead of the addon's own address, which changes across restarts. The list is only written when that range is missing, so an entry added in the calibre-web admin page is no longer erased on every start (https://github.com/alexbelgium/hassio-addons/pull/3010)
 

calibre_web/Dockerfile

@@ -35,11 +35,9 @@ RUN \
     && echo '#!/bin/sh' > /usr/bin/xdg-desktop-menu && chmod +x /usr/bin/xdg-desktop-menu \
     && echo '#!/bin/sh' > /usr/bin/xdg-mime && chmod +x /usr/bin/xdg-mime
 
-# Install calibre binaries (provides calibredb required for book downloads)
-# hadolint ignore=DL4006
-RUN \
-    wget -nv -O- https://download.calibre-ebook.com/linux-installer.sh | sh /dev/stdin install_dir=/opt/calibre
-ENV PATH="/opt/calibre:${PATH}"
+# By default the calibre binaries (calibredb, ebook-convert, ebook-meta) are installed at start by
+# the linuxserver/mods:universal-calibre docker mod, set as the default DOCKER_MODS in config.yaml.
+# The xdg-* stubs above keep its calibre_postinstall step quiet.
 
 # Global LSIO modifications
 COPY ha_lsio.sh /ha_lsio.sh

calibre_web/README.md

@@ -97,6 +97,18 @@ This addon supports mounting both local drives and remote SMB shares:
 - **Local drives**: See [Mounting Local Drives in Addons](https://github.com/alexbelgium/hassio-addons/wiki/Mounting-Local-Drives-in-Addons)
 - **Remote shares**: See [Mounting Remote Shares in Addons](https://github.com/alexbelgium/hassio-addons/wiki/Mounting-remote-shares-in-Addons)
 
+### Optional Calibre-Web features
+
+Calibre-Web documents optional extras that a manual installation adds with `pip install calibreweb[metadata]` and similar. **You do not need to install anything here**: the LinuxServer base image this add-on builds on installs Calibre-Web's `requirements.txt` *and* its full `optional-requirements.txt` into the application's virtualenv, so the gdrive, gmail, goodreads, ldap, oauth, metadata, comics and kobo dependencies are all present already. Running `pip install calibreweb[...]` inside the container is not a supported way to enable them: it installs the PyPI distribution of Calibre-Web over an installation that already has those dependencies, and it can disturb the versions the base image pinned. It is also thrown away, because the Supervisor recreates the add-on container on restart.
+
+Optional features are switched on in the Calibre-Web web interface, not in the add-on options, under `Admin` -> `Basic Configuration` -> `Feature Configuration` (for example `Enable Uploads`, `Enable Kobo sync`, `Use Goodreads`).
+
+**Book covers.** The `Fetch Cover from URL` and `Upload Cover from Local Disk` fields only appear on a book's `Edit Metadata` page when `Enable Uploads` is ticked in `Feature Configuration` **and** the logged-in user has the `Upload` permission (`Admin` -> the user -> `Upload`). A missing Python package is not what hides them.
+
+**Conversion, metadata embedding and the other Calibre integrations** use command-line binaries such as `ebook-convert`, `ebook-meta` and `calibredb`. Those are installed at start by the `linuxserver/mods:universal-calibre` docker mod, which is the shipped default of the `DOCKER_MODS` option. If you set `DOCKER_MODS` yourself, keep `linuxserver/mods:universal-calibre` in the list (mods are separated by `|`) or those binaries disappear.
+
+**Other compatible Python packages** can be installed from the add-on's custom script (see the section below); `pip` there points at Calibre-Web's own virtualenv. Such a script runs on every start, and it has to, since the container's writable layer does not persist.
+
 ### Custom Scripts and Environment Variables
 
 This addon supports custom scripts and environment variables:

calibre_web/config.yaml

@@ -116,5 +116,5 @@ schema:
 slug: calibre-web
 udev: true
 url: https://github.com/alexbelgium/hassio-addons/tree/master/calibre_web
-version: "0.6.27.2"
+version: "0.6.27.3"
 video: true