calibre: replace with Calibre-Web-Automated on esh-docker-vm

Retire the linuxserver.io calibre + calibre-web pair. CWA (crocodilestick/calibre-web-automated) is an all-in-one: combined web UI with Calibre backend, auto-ingest via drop folder, scheduled metadata maintenance — single container on :8083. - Reuses the existing library at /mnt/books/calibre/calibre_library (NFS) and the existing calibre-web config at /opt/docker/conf/calibre-web, so user accounts and the book catalogue carry over. - Requires NETWORK_SHARE_MODE=true (library is on NFS; SQLite WAL would corrupt otherwise). - New drop-zone at /mnt/books/calibre/ingest; files placed there are ingested into the library and then removed. - Loses the LSIO desktop Calibre GUI (ports 8082/8181/8281) — run Calibre locally if you need the desktop UI. Old compose dirs (/opt/docker/compose/{calibre,calibre-web}) removed on esh-docker-vm; old images can be pruned at leisure.
2026-04-20 22:14:38 -07:00
parent 8d6921cb75
commit dfdabd1d02
4 changed files with 207 additions and 2 deletions
@@ -44,8 +44,7 @@ General-purpose Docker host at the **ESH home-lab site** (`esteban.net` / `10.0.
 | homeassistant | macvlan `10.0.50.46:8123` | Home automation (direct LAN IP via macvlan on `ens18`) |
 | esphome | host net / 6052 | ESPHome firmware dashboard |
 | mosquitto | 1883 | MQTT broker |
-| calibre | 8082 / 8181 / 8281 | Ebook server |
-| calibre-web | 8083 | Ebook web UI |
+| calibre-web-automated | 8083 | All-in-one ebook library + web UI; replaced `calibre` + `calibre-web` pair on 2026-04-20 |
 | paperless-ngx (+ redis broker + volume-backup sidecar) | 8200 | Document archive; Postgres on `10.0.50.60:5432` |
 | pgadmin (+ volume-backup sidecar) | 5050 | Postgres admin UI |
 | drawio | 8087 / 8447 | Diagram editor |
@@ -0,0 +1,40 @@
+# Calibre-Web-Automated tunables.
+#
+# Copy to .env on the host. The directory paths MUST exist and be
+# writable by PUID:PGID before the first container start.
+
+# Image pin
+CWA_VERSION=latest
+
+# Port on the host (and inside the container — CWA_PORT_OVERRIDE sets both).
+CWA_PORT=8083
+
+# UID/GID owning the mounted files. 2000:2000 matches what the old
+# calibre + calibre-web stacks used on esh-docker-vm.
+PUID=2000
+PGID=2000
+
+TZ=America/Los_Angeles
+
+# NETWORK_SHARE_MODE disables SQLite WAL. REQUIRED when /calibre-library
+# or /config is on NFS / SMB. Leave this on unless you move everything
+# to local disk.
+NETWORK_SHARE_MODE=true
+
+# Optional: enables the Hardcover metadata provider. Sign up at
+# hardcover.app and issue a token. Leave empty if unused.
+HARDCOVER_TOKEN=
+
+# Host directories — use the same library as the old stacks to keep the
+# book catalogue. Migrate the old calibre-web config in place.
+#
+# Example values for esh-docker-vm:
+#   CWA_CONFIG_DIR=/opt/docker/conf/calibre-web-automated
+#   CWA_INGEST_DIR=/mnt/books/calibre/ingest
+#   CWA_LIBRARY_DIR=/mnt/books/calibre/calibre_library
+#
+# ⚠  The ingest directory is a drop zone — files placed there are DELETED
+#    after CWA processes them into the library. Pick a dedicated folder.
+CWA_CONFIG_DIR=
+CWA_INGEST_DIR=
+CWA_LIBRARY_DIR=
@@ -0,0 +1,121 @@
+# calibre-web-automated
+
+All-in-one replacement for the old `calibre` (linuxserver desktop GUI) +
+`calibre-web` (read-only web UI) pair on esh-docker-vm.
+
+Upstream: https://github.com/crocodilestick/Calibre-Web-Automated
+
+## What changes vs. the old pair
+
+| Concern | Old | CWA |
+|---|---|---|
+| Web UI | `calibre-web` on :8083 | `calibre-web-automated` on :8083 |
+| Library management | `calibre` desktop GUI on :8082 | Built into the CWA web UI |
+| Auto-ingest (drop folder) | n/a | `/cwa-book-ingest` drop zone; processed books land in library, source file is **deleted** |
+| Metadata editing | desktop GUI only | Web UI + scheduled tasks |
+| Host containers | 2 | 1 |
+
+Losing the separate `calibre` container also loses the full desktop Calibre
+experience (content server, news fetching, mobile companion apps bound to
+port 8081). If you used those specifically, keep the old calibre container
+or run Calibre locally.
+
+## Volumes
+
+- **`/config`** (`CWA_CONFIG_DIR`) — holds `app.db` (users/settings), logs.
+  **Reusable** from the old calibre-web config. Migration path: point this
+  at `/opt/docker/conf/calibre-web-automated` (new) or just reuse
+  `/opt/docker/conf/calibre-web` directly if you want zero-touch migration.
+- **`/cwa-book-ingest`** (`CWA_INGEST_DIR`) — drop zone. Files dropped here
+  are auto-ingested into the library and then **removed from the drop
+  zone**. Pick a dedicated folder; don't point it at something you care
+  about keeping untouched.
+- **`/calibre-library`** (`CWA_LIBRARY_DIR`) — the Calibre library root
+  (contains `metadata.db` + author/book subdirs). Reuse the existing path
+  so the catalogue is preserved.
+
+## NFS caveat (important)
+
+The library on esh-docker-vm lives on NFS (`/mnt/books/...`). CWA uses
+SQLite for its database; by default it writes in WAL mode, which corrupts
+over NFS. The env var `NETWORK_SHARE_MODE=true` disables WAL — **keep this
+on** as long as `/calibre-library` or `/config` is on a network share.
+
+## Migration plan
+
+1. **Back up the current state** while the old containers are still up:
+   ```bash
+   ssh esh-docker-vm 'tar -C /opt/docker/conf -czf /tmp/calibre-web-config-backup-$(date +%F).tar.gz calibre-web'
+   ```
+   And confirm the library itself already lives in the NAS backup pipeline.
+
+2. **Stop and remove the old stacks** (but leave the library + config in
+   place):
+   ```bash
+   ssh -t esh-docker-vm '
+     cd /opt/docker/compose/calibre     && sudo docker compose down &&
+     cd /opt/docker/compose/calibre-web && sudo docker compose down
+   '
+   ```
+   Port 8083 is now free for CWA.
+
+3. **Create the CWA stack dir + seed .env** (one-time):
+   ```bash
+   ssh -t esh-docker-vm 'sudo mkdir -p /opt/docker/compose/calibre-web-automated /mnt/books/calibre/ingest &&
+     sudo chown lkraven:lkraven /opt/docker/compose/calibre-web-automated &&
+     sudo chown 2000:2000 /mnt/books/calibre/ingest'
+
+   ssh -t esh-docker-vm 'sudo tee /opt/docker/compose/calibre-web-automated/.env > /dev/null <<EOF
+   CWA_VERSION=latest
+   CWA_PORT=8083
+   PUID=2000
+   PGID=2000
+   TZ=America/Los_Angeles
+   NETWORK_SHARE_MODE=true
+   HARDCOVER_TOKEN=
+   CWA_CONFIG_DIR=/opt/docker/conf/calibre-web
+   CWA_INGEST_DIR=/mnt/books/calibre/ingest
+   CWA_LIBRARY_DIR=/mnt/books/calibre/calibre_library
+   EOF'
+   ```
+   `CWA_CONFIG_DIR` points at the **existing** calibre-web config so user
+   accounts and library pointer are kept. CWA will migrate the schema on
+   first launch.
+
+4. **Push the canonical + bring it up**:
+   ```bash
+   mkdir -p stacks-mirror/esh-docker-vm/calibre-web-automated
+   cp stacks/calibre-web-automated/compose.yaml stacks-mirror/esh-docker-vm/calibre-web-automated/
+   scripts/deploy-stack.sh esh-docker-vm calibre-web-automated --compose
+   ssh -t esh-docker-vm 'cd /opt/docker/compose/calibre-web-automated && sudo docker compose up -d'
+   ```
+
+5. **First login** — user `admin`, password `admin123` if this is a fresh
+   config. If you reused the old calibre-web config, your existing users
+   carry over.
+
+6. **Verify**:
+   - Load http://10.0.50.45:8083 → library shows your books
+   - Drop a test `.epub` into `/mnt/books/calibre/ingest/` → watch it
+     appear in the library and get removed from the ingest folder
+   - `ssh esh-docker-vm 'docker inspect calibre-web-automated --format "{{.State.Health.Status}}"'` → healthy
+
+7. **Clean up the old stack directories** (after a week of CWA running
+   cleanly):
+   ```bash
+   ssh -t esh-docker-vm 'sudo rm -rf /opt/docker/compose/calibre /opt/docker/compose/calibre-web'
+   ```
+   Leave the library and old config alone for a while longer — CWA might
+   need a re-init if something unexpected surfaces.
+
+## Homepage
+
+Labeled `homepage.group=Media`. The old Calibre + Calibre-Web cards will
+vanish once their containers are down; the single CWA card takes their
+place.
+
+## Widget
+
+CWA doesn't have a first-class homepage widget yet. If calibre-web's
+widget was in use, it'll stop reporting after migration. No mitigation
+until upstream adds one.
@@ -0,0 +1,45 @@
+# Calibre-Web-Automated — all-in-one replacement for the old
+# `calibre` + `calibre-web` pair. Upstream: https://github.com/crocodilestick/Calibre-Web-Automated
+#
+# The library lives on the NH3 / ESH NAS via NFS, so NETWORK_SHARE_MODE
+# must be on (disables SQLite WAL, which corrupts on NFS).
+#
+# All tunables live in .env — edit that, not this file.
+
+services:
+  calibre-web-automated:
+    image: crocodilestick/calibre-web-automated:${CWA_VERSION:-latest}
+    container_name: calibre-web-automated
+    restart: unless-stopped
+    environment:
+      - PUID=${PUID:-2000}
+      - PGID=${PGID:-2000}
+      - TZ=${TZ:-America/Los_Angeles}
+      - NETWORK_SHARE_MODE=${NETWORK_SHARE_MODE:-true}
+      - CWA_PORT_OVERRIDE=${CWA_PORT:-8083}
+      - HARDCOVER_TOKEN=${HARDCOVER_TOKEN:-}
+    ports:
+      - "${CWA_PORT:-8083}:${CWA_PORT:-8083}"
+    volumes:
+      - ${CWA_CONFIG_DIR}:/config
+      - ${CWA_INGEST_DIR}:/cwa-book-ingest
+      - ${CWA_LIBRARY_DIR}:/calibre-library
+    healthcheck:
+      test: ["CMD-SHELL", "wget -q --spider http://localhost:${CWA_PORT:-8083} || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+    networks:
+      - tnet
+    labels:
+      - homepage.group=Media
+      - homepage.name=Calibre-Web-Automated
+      - homepage.icon=si-calibreweb
+      - homepage.description=eBook library + auto-ingest (esh)
+      - homepage.href=http://10.0.50.45:${CWA_PORT:-8083}
+
+networks:
+  tnet:
+    name: traefik-net
+    external: true