Calibre-Web Automated: a self-hosted ebook library that ingests and converts on its own

The gap CWA fills between Calibre and Calibre-Web

Calibre and Calibre-Web solve different halves of the same problem, and the README is explicit about the split. Containerised Calibre depends on a KasmVNC server instance for its UI, which the project calls near impossible to use on mobile and relatively resource-heavy on a small, low-power server. Calibre-Web fixes that with a lighter web interface, but it lacks core features, so many people end up running both services side by side. CWA's stated goal is to combine the Calibre-Web UI with the Calibre feature set and add automation on top.

The audience is therefore narrow and specific: someone who already has a Calibre library directory, runs a home server, and finds the two-service arrangement annoying. If you only want to browse and download books and never touch metadata or conversion, stock Calibre-Web is less machinery for the same result.

Ingest folders, watchers and the SQLite write-ahead log

The automation is built around file watching. The repository contains an ingest path and a metadata watcher, and the compose file documents that file watching normally uses inotify but switches to polling when needed. That watcher is what turns a dropped file into a library entry, which is the feature the name refers to.

Concurrency is handled by enabling SQLite Write-Ahead Logging on local disks, which the README describes as an optimisation. That choice has a direct consequence: some network filesystems do not fully support WAL or reliable file locking, and the README warns this can cause intermittent database is locked errors or corruption risks. The escape hatch is a single environment variable, NETWORK_SHARE_MODE=true, which disables WAL on both the Calibre metadata.db and the app.db settings database, skips recursive chown operations that often fail on NFS and SMB, and moves the ingest and metadata watchers to polling. The README is honest that network shares remain slower than local disks even with the mode enabled.

The stack is Python, not JavaScript. The pyproject file lists Flask, SQLAlchemy, APScheduler and tornado, with requires-python >=3.10 and classifiers up to Python 3.13. The Dockerfile builds against a LinuxServer Ubuntu Noble base and installs Python 3.13 from the deadsnakes PPA, pulling in Calibre release 9.1.0 and kepubify v4.0.4 as build arguments. Kepubify is the piece that matters for Kobo owners, since it produces the kepub format those devices read.

Installing Calibre-Web Automated with Docker Compose

The README recommends Docker Compose over a plain docker run. The compose file in the repository is the reference: it pins the image crocodilestick/calibre-web-automated:latest, sets PUID and PGID, and requires you to edit TZ to match your location. A HARDCOVER_TOKEN variable is present for using Hardcover as a metadata provider, and it expects an API key from the Hardcover documentation rather than a placeholder you can leave as-is.

services:
  calibre-web-automated:
    image: crocodilestick/calibre-web-automated:latest
    container_name: calibre-web-automated
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/London
      - NETWORK_SHARE_MODE=false

After the container starts, the application listens on port 8083 by default. The compose file notes that CWA_PORT_OVERRIDE can change it, and it is commented out in the shipped example, so leave it commented unless 8083 collides with something else on the host. The README also covers post-install tasks and a default admin login, which is the first thing to change once you can reach the UI.

docker compose up -d
docker compose logs -f calibre-web-automated

The second command is how you watch startup. If library auto-detection is misbehaving, the compose file documents DISABLE_LIBRARY_AUTOMOUNT, which accepts true, yes or 1 and stops the auto-library service from running at startup.

Migrating from stock Calibre-Web without losing your settings

The README has a dedicated section for users migrating from stock Calibre-Web, and the compose comments repeat the procedure: stop the existing Calibre-Web instance, make a copy of its config folder, and bind that copy into the CWA container so user settings carry over. Copy, not move. If the migration goes wrong you still have the original.

This is also where the largest operational risk sits. CWA runs its own ingest and metadata processes against the same library, and the README's warning about WAL and network filesystems applies to any deployment where metadata.db lives on a share. Mounting a config folder from a NAS is a common pattern and one the project explicitly supports, but only with NETWORK_SHARE_MODE=true set. Leaving it false on a share is the configuration most likely to produce the locked-database errors the README describes.

Where CWA is the wrong tool

The README does not document a rollback or downgrade procedure. Releases are tagged, and the compose example pins :latest, which means an unattended restart can move you onto a newer build with no documented way back short of pinning a version yourself. If you need reversible upgrades as a first-class feature, plan for that before you migrate, not after.

Second, Docker is the assumed deployment. There is a kubernetes directory and a docker-compose.yml.dev in the repository, but the install documentation is container-centric. Running CWA directly from source means working through requirements.txt, which is long and includes optional groups for Google Drive, LDAP, OAuth and comic handling. That is a real installation surface, not a two-line setup.

Third, the project's own framing is that it is an all-in-one replacement. If your library is small and static, the automation has nothing to automate. The ingest watcher, the conversion pipeline and the WAL tuning all exist to handle change. A fixed collection of a few hundred books that you never add to gets the Calibre-Web UI with more moving parts.

How CWA differs from Kavita, Komga and Readarr

The related searches show people comparing CWA against Kavita, Komga, Readarr and Booklore, and the distinction is structural rather than a feature checklist. CWA is a front end over a Calibre library on disk. Calibre owns metadata.db, and CWA automates what goes into it. Kavita and Komga are readers with their own libraries and their own scanning model; they do not depend on Calibre being present, and they do not inherit Calibre's metadata database.

That difference decides most adoption questions. If your metadata, tags and series information already live in Calibre and you want that preserved, CWA is the option that keeps it. If you want a comic and manga reader first and do not care about Calibre, a Calibre-centric tool is the wrong shape. Readarr sits elsewhere again: it is about acquiring books, and the README points to Shelfmark as an affiliated downloader that prepares books for integration into a Calibre library. CWA itself states it does not approve of or support piracy and is not responsible for user behaviour, so treat the downloader as a separate project with its own rules.

Licence and the cost of keeping up

CWA is GPL-3.0, stated in the repository and in pyproject as GPLv3+. If you modify and distribute it, the copyleft terms apply to your distributed version. Running it on your own server for your own library is the ordinary case and does not trigger distribution obligations. This is a description of the licence text, not legal advice; check the terms yourself if you plan to redistribute a modified build.

The maintenance picture is active. The last push to the main branch was on 2026-08-07, and the most recent release listed is v4.0.6 on 2026-02-04. The repository is not archived. Upgrade cost is the practical question rather than abandonment risk: because the compose example tracks :latest, staying current is automatic and staying on a known-good version requires you to pin a tag. The Dockerfile exposes CALIBRE_RELEASE and KEPUBIFY_RELEASE as build arguments, currently 9.1.0 and v4.0.4, so a custom build lets you control the Calibre version independently of the CWA release.

Editorial conclusion

Adopt Calibre-Web Automated if you already keep a Calibre library and want a browser UI plus automatic ingest, and you are willing to run it as a Docker container with PUID, PGID and TZ set. Do not adopt it if you need a documented rollback path (the README does not document one) or if you want a system you can run without Docker, since the install instructions are container-based. Before migrating, copy your existing Calibre-Web config folder and bind it into the new container, then verify that metadata.db is writable and that your ingest folder is not on a share until you have set NETWORK_SHARE_MODE=true.

Frequently asked questions

Official sources

1. crocodilestick/Calibre-Web-Automated on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases