esh-pfi-infrastructure/stacks/calibre-web-automated

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:

   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):

   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):

   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:

   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):

   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.