CWA allows you to keep your ebook library accessible & organised and looks good while doing it 😎🦚

\n\n## _Affiliated Projects_ 👬\n\n### Shelfmark: Book Downloader\n\n- An intuitive web interface for searching and requesting book downloads, designed to work seamlessly with Calibre-Web-Automated. This project streamlines the process of downloading books and preparing them for integration into your Calibre library\n\n> [!IMPORTANT] \n> CWA does not approve of or support piracy of copyrighted materials and is not responsible for user behaviour\n\n[ $\"Get$ ](https://github.com/calibrain/shelfmark)\n\n___\n\n### Calibre-Web Companion\n\n- Built with **Flutter** and using **Material You**, [**Calibre Web Companion**](https://github.com/doen1el/calibre-web-companion) is an **unofficial companion application** for **Calibre Web** & **Calibre Web Automated** that allows you to browse your book collection and download books directly on your device, providing a much **more modern, mobile-friendly UX** than either service can currently provide on its own\n\n
\n\n[![Calibre Web Companion Preview](https://github.com/crocodilestick/Calibre-Web-Automated/raw/main/README_images/cw-companion-screenshots.png)](https://github.com/doen1el/calibre-web-companion)\n\n[ $\"Get$ ](https://play.google.com/store/apps/details?id=de.doen1el.calibreWebCompanion)\n[ $\"Get$ ](https://f-droid.org/en/packages/de.doen1el.calibreWebCompanion/)\n[ $\"Get$ ](https://github.com/doen1el/calibre-web-companion)\n\n## Join our Community! ❤️\n\n- I want to say a **big thanks** 🙏 to all the members of this community that have taken the time to participate in the testing and development of this project and we encourage anyone who would like to to contribute in some way. Anyone of any level is welcome and every little helps!\n- **For anyone that wish to contribute to this project in some way**, please reach out on our Discord Server and see how you can best get involved:\\\n \\\n [![](https://dcbadge.limes.pink/api/server/https://discord.gg/EjgSeek94R)](https://discord.gg/EjgSeek94R)\n\n- Or alternatively make your own companion project, come hang out and or come get help if you're facing issues :)\n\n## 🚨 Deploying on Network Shares (NFS/SMB) 🚨\n\n- CWA now supports network-share deployments via `NETWORK_SHARE_MODE=true`\n - This disables SQLite WAL on `metadata.db` and `app.db` to prevent locking issues\n - Skips recursive ownership changes that often fail on NFS/SMB\n - Switches ingest/metadata watchers to a polling-based watcher for reliability\n- Network shares are still slower than local disks, but are now fully supported with this mode enabled\n\n### Network shares and SQLite WAL mode\n\n- CWA optimizes SQLite concurrency by enabling Write-Ahead Logging (WAL) on local disks.\n- Some network filesystems (NFS/SMB) do not fully support WAL or reliable file locking, which can cause intermittent \"database is locked\" errors or corruption risks.\n- If you are deploying on a network share, set the following environment variable to disable WAL:\n\n - `NETWORK_SHARE_MODE=true`\n\nThis tells CWA to avoid enabling WAL on the Calibre `metadata.db` and the `app.db` settings database. It also disables recursive ownership changes (`chown`) performed by init/maintenance scripts to avoid permission issues on network filesystems. Default is `false` (WAL enabled) for better performance on local disks.\n\n#### File watching on network shares\n\n- By default, CWA uses Linux `inotify` (via `inotifywait`) to detect new files in the ingest folder with minimal latency and overhead.\n- On network shares (NFS/SMB), filesystem events can be unreliable or unavailable. When `NETWORK_SHARE_MODE=true` is set, CWA switches the ingest and metadata watcher services to a polling-based watcher that periodically scans for changes. This improves reliability on NAS/network mounts at the cost of slightly higher I/O and up to a few seconds of latency.\n- On Docker Desktop (Windows/macOS), the container runs on a LinuxKit/WSL2 VM and host-mounted paths may not propagate `inotify` events reliably. CWA auto-detects Docker Desktop at startup and prefers the same polling watcher for reliability.\n- Advanced: You can also force polling regardless of share mode by setting `CWA_WATCH_MODE=poll`.\n\n### Running behind multiple proxies (Cloudflare Tunnel, reverse proxy)\n\n- CWA uses Werkzeug's ProxyFix middleware to properly handle `X-Forwarded-For`, `X-Forwarded-Proto`, and other proxy headers.\n- By default, it trusts **1 proxy** in the chain. If you have multiple proxies (e.g., Cloudflare Tunnel → nginx → CWA), set:\n\n - `TRUSTED_PROXY_COUNT=2` (or the total number of proxies in your chain)\n\n- **Why this matters**: Session protection validates requests based on the client's IP address. If ProxyFix doesn't trust enough proxies, it may see different IPs between requests, causing \"Session protection triggered\" warnings and forcing re-login.\n- **Troubleshooting**: If you see frequent session protection warnings in logs, check your proxy chain depth and adjust this variable accordingly.\n\n## **_Features:_**\n\n### CWA supports all Stock CW Features:\n| | | |\n| :---: | :---: | :---: |\n| Modern & responsive Bootstrap 3 HTML5 interface | Comprehensive user management with per-user permissions | OPDS feed for ereader apps |\n| eBook metadata editing and deletion support | Metadata download from various sources (extensible via plugins) | eBook download restriction to logged-in users |\n| Public user registration support | Send eBooks to E-Readers with a single click | Sync Kobo devices with your Calibre library |\n| In-browser eBook reading support for multiple formats | Content hiding based on categories and Custom Column content per user | \"Magic Link\" login for easy access on eReaders |\n| Enhanced OAuth 2.0/OIDC authentication with auto-discovery | Advanced search and filtering options | Multilingual user interface supporting 20+ [languages](https://github.com/janeczku/calibre-web/wiki/Translation-Status) |\n\n## Plus these _**CWA Specific Features**_ on top:\n\n#### Click a feature below to read about it in more detail:\n\n| | | |\n| :---: | :---: | :---: |\n| [Automatic Ingest Service ✨](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#automatic-ingest-service-) | [Automatic Conversion Service 🔃](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#automatic-conversion-service-) | [Automatic Enforcement of Covers & Metadata 👀📔](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#automatic-enforcement-of-changes-made-to-covers--metadata-through-the-calibre-web-ui-) |\n| [Batch Editing & Deletion 🗂️](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#batch-editing--deletion-️️) | [Automated Back Up Service 🔒](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#automated-back-up-service-) | [Automated Setup Experience for New Users 🦮](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#library-auto-detect-️) |\n| [Automatic EPUB Fixer Service 🔨](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#automatic-epub-fixer-service-) | [Multi-Format Conversion Service 🌌](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#simple-to-use-multi-format-conversion-service-) | [Library Auto-Detect 📚🕵️](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#library-auto-detect-️) |\n| [Smart Duplicate Detection & Management 🔍](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#smart-duplicate-detection--management-) | [Magic Shelves 🪄📚](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#magic-shelves-) | [Auto-Send to eReader 📧⚡](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#auto-send-to-ereader-) |\n| [Automatic Metadata Fetch on Ingest 🏷️🤖](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#automatic-metadata-fetch-on-ingest-) | [Deep Stats & Analytics 📊✨](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#deep-stats--analytics-) | [Easy Dark/ Light Mode Switching ☀️🌙](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#easy-dark-light-mode-switching-️) |\n| [Internal Update Notification System 🛎️](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#internal-update-notification-system-️) | [Auto-Compression of Backed Up Files 🤐](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#auto-compression-of-backed-up-files-) | [Additional Metadata Providers 🗃️](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#additional-metadata-providers-️) |\n| [KOReader Syncing (KOSync) 📖⚡](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#koreader-syncing-kosync-) | [Enhanced OAuth 2.0/OIDC Authentication 🔐](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#enhanced-oauth-20oidc-authentication-) | [EPUB Fixer 2.0 📧✅](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#epub-fixer-20-) |\n| [Automatic Hardcover ID Fetch 💜🤖](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#automatic-hardcover-id-fetch-) | [Server Stats Tracking Page 📍](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#server-stats-tracking-page-) | [Enhanced Send-to-eReader Modal ✉️](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#enhanced-send-to-ereader-modal-) |\n\n#### **Automatic Ingest Service** ✨\n- CWA currently supports automatic ingest of 27 different popular ebook formats\n- Users can configure the services behavior to ignore and/or have certain formats automatically converted to other formats in the Admin Panel\n\n#### **Automatic Conversion Service** 🔃\n- On by default though can be toggled off in the CWA Settings page, with EPUB as the default target format\n - _Available target formats include:_ **EPUB**, **MOBI**, **AZW3**, **KEPUB** & **PDF**\n- Upon detecting new files in the Ingest Directory, if any of the files are in formats the user has configured CWA to auto-convert to the current target format,\n- The following **28 file types are currently supported:**\n - _.acsm, .azw, .azw3, .azw4, .mobi, .cbz, .cbr, .cb7, .cbc, .chm, .djvu, .docx, .epub, .fb2, .fbz, .html, .htmlz, .lit, .lrf, .odt, .pdf, .prc, .pdb, .pml, .rb, .rtf, .snb, .tcr, .txtz_\n - _Note: .acsm requires an additional Calibre plugin_\n\n#### **Automatic Enforcement of Changes made to Covers & Metadata through the Calibre-Web UI!** 👀📔\n- In stock Calibre-Web, any changes made to a book's **Cover and/or Metadata** are only applied to how the book appears in the Calibre-Web UI, changing nothing in the ebook's files like you would expect\n- This results in a frustrating situation for many CW users who utilise CW's Send-To-Kindle function, and are disappointed to find that the High-Quality Covers they picked out and carefully chosen Metadata they sourced are completely absent on all their other devices! UGH!\n- CWA's **Automatic Cover & Metadata Enforcement Feature** makes it so that **WHATEVER** you changes you make to **YOUR** books, **_are made to the books themselves_**, as well as in the Web UI, **making what you see, what you get.**\n\n#### **Automated Back Up Service** 🔒\n- Worried what will happen if something goes wrong during one of CWA's automated functions? Don't be!\n- By default, the originals all files processed by CWA are stored in `/config/processed_books` though this can be toggled in the CWA Settings panel\n\n#### **Smart Duplicate Detection System & Management** 🔍\n- Hybrid SQL + fuzzy matching detects duplicates missed by traditional scans\n- Post-ingest checks and scheduled incremental scans\n- One-click merge, batch operations, and optional auto-resolution\n- Configurable matching rules, thresholds, and format awareness\n\n![](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README_images/duplicate-detection-system.gif?raw=true)\n\n#### **Magic Shelves** 🪄📚\n- Dynamic, rules-based shelves with rich filters and AND/OR logic\n- Pre-built templates (Recent, Highly Rated, No Cover, Incomplete Series, etc.)\n- Real-time updates with cached counts and tooltips\n- Kobo sync support and optional tag-based syncing\n\n![](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README_images/magic-shelf-showcase.gif?raw=true)\n\n#### **Auto-Send to eReader** 📧⚡\n- Automatically email new books after ingest\n- Configurable delay to allow metadata/enforcement/EPUB fixes first\n- Format selection and multi-recipient sending\n- Works with per-user settings and optional custom email subjects\n\n#### **Automatic Metadata Fetch on Ingest** 🏷️🤖\n- Optionally fetch and apply metadata automatically during ingest\n- Provider hierarchy is respected with smart fallback\n- Choose whether to overwrite existing fields or only fill missing data\n- Works seamlessly with Auto-Send and EPUB Fixer workflows\n\n#### **Deep Stats & Analytics** 📊✨\n- Full analytics center with user activity, library, API usage, and time-based insights\n- Export sections to CSV for offline analysis\n- User-specific filtering and custom date ranges\n- Interactive charts with dark-mode styling\n\n![](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README_images/cwa-stats-showcse.gif?raw=true)\n\n#### **Enhanced Send-to-eReader Modal** ✉️\n- Send to multiple devices at once\n- Ad-hoc email addresses supported for sharing with friends, family or even temporary devices\n\n![](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README_images/new-send-to-ereader-modal.png?raw=true)\n\n#### **Automatic EPUB Fixer Service** 📧✅\n- Ever had it where you're super excited to start reading your next book but for some reason, Amazon's Send-to-Kindle service just keeps rejecting it? Well no more!\n\n- Originally developed by [innocenat](https://github.com/innocenat/kindle-epub-fix), this tool corrects the following potential issues for every EPUB processed by CWA:\n - Fixes UTF-8 encoding problem by adding UTF-8 declaration if no encoding is specified\n - Fixes hyperlink problem (result in Amazon rejecting the EPUB) when NCX table of content link to `` with ID hash.\n - Detect invalid and/or missing language tag in metadata, and prompt user to select new language.\n - Remove stray `` tags with no source field.\n - Resolves several EPUB compatibility issues, such as UTF-8 encoding, hyperlink problems, invalid/missing language tags, and stray image tags.\n - Repairs malformed language tags, XML declarations, and UTF-8 headers\n - Cleans invalid NCX links, broken CSS/fonts, and stray image tags\n- This **ensures maximum comparability** for each EPUB file with the Amazon **Send-to-Kindle** service and for those who don't use Amazon devices, has the side benefit of cleaning up your lower quality files!\n- Enabled by default, with per-run backups in `/config/processed_books`\n- Bulk processing of whole library with progress tracking available in the Admin Panel\n\n![CWA EPUB Fixer Service Web UI](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README_images/CWA-new-process-ui.gif?raw=true)\n\n#### **Simple to use Multi-Format Conversion Service** 🌌\n- This utility gives the user the option to either keep a copy of the original of all converted files in `/config/processed_books` or to trust the process and have CWA simply convert and replace those files (not recommended)\n- Full usage details can be found [here](https://github.com/crocodilestick/Calibre-Web-Automated/blob/main/README.md#the-convert-library-tool)\n\n#### **Additional Metadata Providers** 🗃️\n- Users can now make use of [isbndb.com](https://isbndb.com/)'s huge database when fetching metadata for the books in their library!\n- Access is being provided via [ibdb.dev](https://ibdb.dev/) thanks to a generous donation to the community by [@chad3814](https://www.github.com/chad3814)\n- [Hardcover](https://hardcover.app/) and Kobo metadata providers are supported, alongside new LitRes support\n\n#### **KOReader Syncing (KOSync)** 📖⚡\nBuilt-in KOReader progress sync with automatic book identification:\n- **Book Identification:** Auto-generates KOReader-compatible partial MD5 checksums for all books\n- **Unified Progress:** Syncs KOReader → CWA reading status → Kobo devices\n- **Zero Config:** Checksums generated on startup and import, no manual setup\n- **Modern Auth:** RFC 7617 HTTP Basic Auth with existing CWA accounts\n- **Plugin Available:** Download from `/kosync` endpoint on your CWA instance\n\n#### **Enhanced OAuth 2.0/OIDC Authentication** 🔐\n- **Auto-Discovery:** Automatic endpoint configuration via OIDC metadata URLs for seamless setup with providers like Keycloak, Authentik, Google, and Azure AD\n- **Manual Override:** Full manual control over OAuth endpoints when auto-discovery isn't available\n- **Field Mapping:** Configurable JWT field extraction for usernames and emails to work with any provider's token structure\n- **Group-Based Roles:** Automatic admin role assignment based on OAuth provider groups\n- **Testing Tools:** Built-in connection testing and validation to ensure your configuration works before going live\n- **Enterprise Ready:** Support for custom scopes, multiple authentication methods, and comprehensive troubleshooting\n- **📖 [Full OAuth Configuration Guide](https://github.com/crocodilestick/Calibre-Web-Automated/wiki/OAuth-Configuration)** for detailed setup instructions\n\n#### **Automatic Hardcover ID Fetch** 💜🤖\n- Background task auto-populates missing Hardcover IDs\n- Configurable scheduling with progress tracking in Tasks\n- Graceful handling of invalid tokens\n\n#### **Library Auto-Detect** 📚🕵️\n - Made to **MASSIVELY** simplify the setup process for both **new and existing users** alike\n - **New Users without existing Libraries:** 🆕\n - **No library? No problem!**\n - New users without existing Calibre Libraries no longer need to copy and paste `metadata.db` files and point to their location in the Web UI, CWA will now automatically detect the lack of Library in your given bind and automatically create a new one for you! It will even automatically register it with the Web UI so you can really hit the ground running\n - **New or Existing Users with Existing Libraries:**\n - Simply bind a directory containing your Calibre Library (search is done recursively so it doesn't matter how deep in the directory it is) and CWA will now automatically find it and mount it to the Web UI\n - Should you bind a directory with more than 1 Calibre Library in it, CWA will intelligently compare the disk sizes of all discovered libraries and mount the largest one\n - _CWA supports only one library per instance though support for multiple libraries is being investigated for future releases_\n - _In the meantime, users with multiple libraries who don't want to consolidate them are advised to run multiple, parallel instances_\n\n\n\n#### **Internal Update Notification System** 🛎️\n - Users will now be automatically notified of the availability of new updates from within the Web UI\n - Automatically triggered by a difference between the version number of the most recent GitHub release and the version installed\n - Set to only show once per calendar day until updated as to not be annoying\n - _Visible to Admin users only_\n\n#### **Manual Library Refresh** ♻️\n - Ever had books get stuck in the ingest folder after an unexpected power-cut ect.? Well say goodbye to having to manually copy the","has_starred","hub_user","immutable_tags_settings",{"_343":11,"_344":345},"enabled","rules",[346],".*","is_automated","permissions",{"_350":21,"_351":11,"_352":11},"read","write","admin","user","storage_size",428943266672,"isOrg","reponame","tag","sha256:54ab8b491e0dab658132ffc2583dd764895f7cf09531c1bf006df353820c5b66","canDeleteTags","isHubSbxKitsEnabled","currentTab","tagAttestations","displaySecurityMetadata","showSbxLogoOverride","routes/_layout.layers.$namespace.$reponame.$tag.(images).($imageUrlDigest)._index",{"_27":28,"_296":-7,"_294":-7,"_295":-7,"_29":368,"_35":359,"_372":-7,"_373":11},{"_31":32,"_33":34,"_35":36,"_37":38,"_39":40,"_41":369,"_67":68,"_69":34,"_70":71,"_72":73,"_74":75,"_76":77,"_78":50,"_79":68,"_80":59,"_81":21},[370,371],{"_44":45,"_35":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":48,"_56":-5,"_57":38,"_58":59,"_60":-5},{"_44":62,"_35":63,"_47":48,"_49":64,"_51":65,"_53":54,"_55":48,"_56":-5,"_57":66,"_58":59,"_60":-5},"imageWithLayers","hasPermissionToViewRepoSettings","actionData","errors"]

crocodilestick/calibre-web-automated:dev