calibre-web: your
Calibre library online

Run these commands on the Docker host; the example container is named calibre-web. The first should list /books/metadata.db; the second should print readable:

docker exec calibre-web ls -la /books/metadata.db
docker exec -u abc calibre-web sh -c 'test -r /books/metadata.db && echo readable'

If the file is missing, point the Compose host path to the full Calibre library and inspect the /books mount with docker inspect calibre-web --format '{{json .Mounts}}'. If it exists but is unreadable, correct PUID/PGID and directory read/traverse permissions. If both tests pass, enter /books under Location of Calibre database and save. You do not need to delete /config.

Titles come from metadata.db, but the actual book files must also be accessible. On the Docker host, confirm that the full library is mounted. This command should find an EPUB; use another extension if your library has no EPUBs.

docker exec -u abc calibre-web sh -c 'find /books -type f -iname "*.epub" -print -quit'

No file: mount or copy the entire library, preserving Calibre's author/title directories. File exists but a regular user cannot download: check Downloads Allowed for that account. If even the administrator fails, check file permissions. If it fails only via the proxy, compare the local and public addresses, then inspect proxy logs and file-size limits.

On the Docker host, inspect the actual config mount. It should point to persistent storage at /config inside the container, with app.db in the original host directory.

docker inspect calibre-web --format '{{range .Mounts}}{{println .Source .Destination}}{{end}}'
ls -la ./config

If starting Compose from another directory created a new empty host path, stop the service, locate the original config directory or backup, restore the original mount, and start again. Do not erase the old volume. Keep the book library and app.db separately.

On the service host, request the local OPDS address as a regular reader. The command prompts for a password; do not put it in the URL or shell history. Use HTTPS when testing from another machine.

curl --user reader -o /dev/null -sS -w '%{http_code}\n' http://127.0.0.1:8083/opds

A local 401 means check the account password and the client's authentication fields; for 403, check browse and download permissions. If the local URL works but the proxy fails, confirm that the proxy preserves the /opds path and authentication, testing GET and HEAD separately. Then compare the URL saved in the client.

In a browser, sign in as the same reader and open a downloadable EPUB. Confirm Downloads Allowed and Kobo sync are enabled. If syncing selected shelves, put that book on a selected shelf and retry. If the count remains zero, temporarily increase logging under Basic configuration → Logfile configuration, sync the device once, and inspect the container log:

docker logs --tail=100 calibre-web

No Kobo request: check the device's api_endpoint, network, and HTTPS. Rejected request: check token and permissions. Catalog appears but conversion fails: check the format and conversion tools inside the container. Restore the previous log level afterward.

Check which app.db, config mount, secret key, and proxy authentication headers the service actually uses. Stop writes, restore the pre-upgrade code or image and a matching config backup in an isolated directory, then address any database migration issue.

Try the same file via the local address. If local upload succeeds but the domain fails, the proxy or gateway is the likely limit. For Nginx, inspect the active config and error log on the proxy host:

sudo nginx -T 2>/dev/null | grep -n client_max_body_size
sudo tail -n 80 /var/log/nginx/error.log

If the log says client intended to send too large body, set client_max_body_size appropriately in the correct site config, verify with sudo nginx -t, and reload. If you do not use Nginx or the local request also fails, check the actual gateway or application limit. Do not raise limits without checking permissions and disk space.

Confirm that the process uses this installation's Python environment rather than system Python. Install missing dependencies with the same venv interpreter, then retry. Avoid mixing pip environments, source checkouts, and service units.

Ask another administrator to reset it in user management if possible. Otherwise stop the running instance, identify and back up the active app.db, and run the following from the source directory using the same Python environment. Replace the path with your actual application database path (the systemd example uses /var/lib/calibre-web/app.db), not your library's metadata.db. Restart and sign in afterward.

read -r -s -p 'New password: ' new_password; echo
./venv/bin/python3 cps.py -p /var/lib/calibre-web/app.db -s "admin:$new_password"
unset new_password

This keeps the literal password out of shell history, but the -s argument may still be visible to other processes on the same host while the command runs. Use a trusted host and private terminal. Docker and installer paths and executables differ; do not copy this source-install command unchanged.

Downloading and in-browser reading use different paths. The built-in reader unpacks EPUB content and loads its HTML, CSS, and scripts in the browser. A malformed EPUB may not display, and a file containing untrusted scripts should not be opened in the built-in reader. Test a trusted local copy first; download and use a separate reader if necessary.

Temporarily raise the log level and enable the access log under calibre-web's Basic configuration → Logfile configuration. On the Kobo, search for devmodeon and enable developer logging in the device information page. Request /kobo/<token>/v1/library/sync in a browser, inspect the returned metadata and download links, and compare the logs to isolate an account, proxy, format, or device problem. Keep the token private.

Avoid writing to the same metadata.db from both apps at once. Stop one before editing metadata, bulk importing, or maintaining the library. On a NAS, avoid multiple processes writing to the database concurrently.