esh-pfi-infrastructure/stacks/calibre-web-automated/README.md

# 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.