Self-Hosting Calibre-Web Automated with Docker

Docker Compose Configuration

Get Calibre-Web Automated running in under five minutes. Drop ebooks into a folder — they get converted to EPUB, deduplicated, and added to your library automatically.

# docker-compose.yml
services:
  calibre-web-automated:
    image: crocodilestick/calibre-web-automated:v4.0.6
    container_name: calibre-web-automated
    restart: unless-stopped
    ports:
      - "8083:8083"   # Web UI
    environment:
      - PUID=1000                    # Your user ID (run 'id -u' to check)
      - PGID=1000                    # Your group ID (run 'id -g' to check)
      - TZ=America/New_York          # Your timezone
      - CWA_AUTOCONVERT=true         # Auto-convert ingested books to EPUB
      # - NETWORK_SHARE_MODE=true    # Uncomment if library is on NFS/SMB
      # - CWA_PORT_OVERRIDE=8083     # Change internal port if needed
    volumes:
      - cwa-config:/config                  # App config and database
      - /path/to/ebook-library:/calibre-library  # Calibre library
      - /path/to/ingest:/cwa-book-ingest    # Drop books here for auto-import
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8083"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  cwa-config:

Start it:

docker compose up -d

Access the web UI at http://your-server:8083. Default credentials: admin / admin123 — change these immediately.

What Is Calibre-Web Automated?

Calibre-Web Automated (CWA) wraps the familiar Calibre-Web interface with a layer of automation that eliminates the tedious parts of ebook library management. Where standard Calibre-Web requires you to manually add books through the UI or maintain a separate Calibre desktop installation, CWA watches an ingest folder and handles everything: format detection, conversion to EPUB, metadata enrichment, duplicate checking, and library insertion — all without human intervention.

The project hit 5,000+ GitHub stars by solving a real pain point: Calibre desktop is powerful but requires a GUI and manual operation. Calibre-Web is a great reader but has no automation. CWA bridges the gap.

Feature	Calibre-Web	Calibre-Web Automated
Web-based reading	Yes	Yes
OPDS feed	Yes	Yes
Auto-import from folder	No	Yes (28 formats)
Auto-convert to EPUB	No	Yes
Duplicate detection	No	Yes (SQL + fuzzy matching)
KOReader sync	No	Yes (built-in)
Magic Shelves	No	Yes (rule-based)
Auto-send to eReader	No	Yes (scheduled email)
Analytics dashboard	No	Yes
Requires Calibre desktop	Yes (for library management)	No

Initial Setup

After starting the container:

1. Open http://your-server:8083 and log in with admin / admin123
2. Go to Admin → Change Password and set a strong password
3. Under Admin → Basic Configuration, verify the library path shows /calibre-library
4. Enable EPUB conversion under Admin → CWA Settings if not already active
5. Test the ingest pipeline: drop any .epub or .pdf file into your ingest folder and watch it appear in the library within seconds

If you’re migrating from an existing Calibre-Web instance, mount the same /config folder — CWA is backwards-compatible with standard Calibre-Web configuration.

Configuration

Auto-Import and Conversion

CWA watches /cwa-book-ingest for new files. When a book lands there:

1. Format is detected (supports 28 formats: EPUB, PDF, MOBI, AZW3, DOCX, FB2, HTML, LIT, ODT, RTF, CBZ, DJVU, and more)
2. If CWA_AUTOCONVERT=true, non-EPUB files are converted to EPUB using Calibre’s conversion engine
3. Metadata is extracted and enriched
4. Duplicate detection runs (hybrid SQL + fuzzy title matching)
5. Book is added to the Calibre library
6. Original file is processed (kept or removed based on settings)

Environment Variables

Variable	Default	Description
PUID	1000	Process user ID — match your host user
PGID	1000	Process group ID — match your host group
TZ	Etc/UTC	Container timezone
CWA_AUTOCONVERT	true	Auto-convert ingested books to EPUB
NETWORK_SHARE_MODE	false	Use polling instead of inotify for NFS/SMB
CWA_PORT_OVERRIDE	8083	Override the internal web server port

Network Share Mode

If your ebook library or ingest folder lives on an NFS or SMB share, Linux inotify won’t detect new files reliably. Set NETWORK_SHARE_MODE=true to switch CWA’s file watcher to polling mode. This uses slightly more CPU but works across all network filesystems.

Magic Shelves

Magic Shelves are dynamic, rule-based collections. Create rules using AND/OR logic to automatically group books by author, tag, format, date added, or any metadata field. Shelves update in real-time as new books are ingested.

Example: A shelf that automatically collects “all EPUB books tagged ‘sci-fi’ added in the last 30 days” without manual curation.

KOReader Sync

CWA includes a built-in KOReader sync server. If you read on a Kobo, Kindle (with KOReader), or other e-ink device running KOReader, reading progress syncs automatically between devices without a separate sync service. Toggle this under Admin → CWA Settings.

Reverse Proxy

For remote access with HTTPS, put CWA behind a reverse proxy. Example for Nginx Proxy Manager:

• Scheme: http
• Forward Hostname: calibre-web-automated (container name)
• Forward Port: 8083
• Enable SSL with Let’s Encrypt

For Caddy or Traefik configuration, see Reverse Proxy Setup.

Backup

Back up two things:

1. Config volume (/config) — contains the application database, user accounts, and settings
2. Calibre library (/calibre-library) — contains metadata.db and all your ebook files

# Stop the container first to ensure database consistency
docker compose stop calibre-web-automated

# Back up config
tar czf cwa-config-backup-$(date +%F).tar.gz /path/to/config

# Back up library (if not already backed up elsewhere)
tar czf cwa-library-backup-$(date +%F).tar.gz /path/to/ebook-library

docker compose start calibre-web-automated

The ingest folder (/cwa-book-ingest) doesn’t need backing up — it’s a temporary staging area.

For automated backups, see Backup Strategy.

Troubleshooting

Books not appearing after dropping into ingest folder

Symptom: Files sit in /cwa-book-ingest but never get processed.

Fix: Check file permissions. The container runs as PUID/PGID — the ingest folder and files must be readable by that user. If using NFS/SMB, set NETWORK_SHARE_MODE=true. Check container logs: docker compose logs calibre-web-automated.

Conversion fails for certain formats

Symptom: Some formats (especially DJVU, LIT, or older formats) fail to convert.

Fix: Check logs for Calibre conversion errors. Some formats with DRM will fail — CWA cannot strip DRM. Ensure the source file isn’t corrupted by testing it in Calibre desktop first.

Database locked errors

Symptom: “database is locked” errors in logs, especially on network shares.

Fix: Set NETWORK_SHARE_MODE=true to disable SQLite WAL mode, which is incompatible with some network filesystems. If the issue persists, ensure no other process (like a separate Calibre desktop instance) is accessing metadata.db simultaneously.

High CPU usage

Symptom: Container pegs CPU at 100% during ingest.

Fix: This is normal during book conversion — EPUB conversion is CPU-intensive. If you’re ingesting hundreds of books at once, expect sustained CPU usage. The conversion queue processes books sequentially. CPU returns to idle once the queue is empty.

Resource Requirements

Metric	Value
RAM (idle)	~120 MB
RAM (during conversion)	~300-500 MB
CPU (idle)	Negligible
CPU (conversion)	1 core per active conversion
Disk (application)	~500 MB
Disk (library)	Depends on your collection

CWA is heavier than standard Calibre-Web (~50 MB idle) because it bundles the full Calibre conversion engine. A Raspberry Pi 4 can run it, but expect slower conversions.

Verdict

If you manage an ebook library, Calibre-Web Automated removes the most annoying part of self-hosted ebook management — the manual import and conversion loop. Drop files into a folder and they appear in your library, converted, deduplicated, and organized. The KOReader sync, Magic Shelves, and auto-send features push it well beyond what standard Calibre-Web offers.

The trade-off is resource usage: CWA bundles the full Calibre engine, so it’s heavier than vanilla Calibre-Web. If you only need a web reader for an existing library and never add books, stick with Calibre-Web. If you regularly download or receive ebooks and want hands-off library management, CWA is the right tool.

Related

• How to Self-Host Calibre-Web
• How to Self-Host Audiobookshelf
• How to Self-Host Kavita
• Calibre-Web vs Kavita
• Best Self-Hosted Media Servers
• Best Self-Hosted Media Organization
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy