Installation

Installation

Calibre-Web-NextGen ships as a single Docker image:

ghcr.io/new-usemame/calibre-web-nextgen:latest

It's a drop-in for the standard Calibre-Web-Automated (CWA) image. Switching keeps everything — your books, users, settings, shelves and the Read checkmarks you've set all live in the folders you mount into the container (/config and /calibre-library), not inside the image. Nothing is converted or deleted, and you can go back to your old image with the same one-line change in reverse.

For the shortest possible path, see Quick Start. Coming from another image? See Migrating.

---

Not using a terminal? Pick your platform

Every guide covers both a fresh install and switching from stock CWA, and tells you how to update later on that platform (on most NAS GUIs a "restart" does not pull a new image — you have to re-pull, and each guide shows exactly how).

You run Docker through…	Guide
Synology (Container Manager / DSM 7.2+)	synology.md
Unraid (Docker tab)	unraid.md
Portainer (Stacks)	portainer.md
TrueNAS SCALE (Apps)	truenas.md
A terminal / docker compose	compose.md
QNAP, Dockge, something else	not written yet — open an issue or ask on Discord and we'll walk you through it

---

Full Docker Compose setup

A more complete compose file, with each option documented:

services:
  calibre-web:
    image: ghcr.io/new-usemame/calibre-web-nextgen:latest
    container_name: calibre-web
    environment:
      # Match your host user/group so files in your library
      # are writable from both the container and the host.
      - PUID=1000
      - PGID=1000

      # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      - TZ=America/New_York

      # Override the in-container port if you need to.
      # If set below 1024, also uncomment cap_add below.
      - CWA_PORT_OVERRIDE=8083

      # Set this if your /config or /calibre-library volumes are
      # on an NFS or SMB share. See "Network shares" below.
      - NETWORK_SHARE_MODE=false

      # If you sit behind multiple proxies (e.g. Cloudflare Tunnel
      # then nginx then CWA), set this to the total proxy count so
      # session protection sees the right client IP. Default 1.
      - TRUSTED_PROXY_COUNT=1

      # Optional: Hardcover API token for the Hardcover metadata
      # provider. Free; sign up at https://hardcover.app/account/api
      # - HARDCOVER_TOKEN=eyJhbGciOiJIUzI1NiI...

    volumes:
      # Settings, user database, logs. Empty folder for new installs;
      # for existing CWA users, point at your existing /config.
      - /path/to/config:/config

      # Your Calibre library. New install? Use an empty folder and
      # CWA will set one up. Existing user? Point at the folder
      # containing your metadata.db.
      - /path/to/library:/calibre-library

      # Drop new books here to import them. WARNING: files in this
      # folder are DELETED after processing. Don't point this at a
      # folder you also use as long-term storage.
      - /path/to/ingest:/cwa-book-ingest

      # Optional: bind your existing Calibre plugins folder
      # - /path/to/calibre-plugins:/config/.config/calibre/plugins

    ports:
      - 8083:8083

    # Uncomment if CWA_PORT_OVERRIDE is below 1024.
    # cap_add:
    #   - NET_BIND_SERVICE

    restart: unless-stopped

What goes in each volume

Volume	What it is	Notes
/config	App settings, user accounts, OAuth tokens, KOReader sync state, logs	Empty folder for new installs. Carries over from CWA verbatim.
/calibre-library	Books and Calibre's metadata.db	If empty, CWA creates a fresh library. If multiple metadata.db files exist inside, CWA picks the largest.
/cwa-book-ingest	Drop zone for new books	Files here are deleted after processing. Don't park books here long-term.

Don't nest the binds. All three should be separate top-level folders. Putting ingest inside library produces recursive ingest behavior.

---

Running with Podman

Calibre-Web-NextGen is a standard OCI image, so it runs under Podman too — same image, no separate build:

podman run -d --name calibre-web \
  -e PUID=1000 -e PGID=1000 -e TZ=America/New_York \
  -p 8083:8083 \
  -v /path/to/config:/config \
  -v /path/to/library:/calibre-library \
  -v /path/to/ingest:/cwa-book-ingest \
  ghcr.io/new-usemame/calibre-web-nextgen:latest

Rootless Podman remaps user IDs, so if the container can't write to your volumes, add --userns=keep-id (or run it rootful). Podman also has native automatic updates (podman auto-update) with rollback — a step-by-step guide is coming once we've verified it against this image.

Next: First Run → Updating.