Deploy Calibre-Web trên Docker: Xây dựng thư viện E-Book tự host với tính năng Gửi lên Kindle

HomeLab tutorial - IT technology blog
HomeLab tutorial - IT technology blog

Vấn đề với E-Book nằm rải rác khắp nơi

Nếu bạn đã sưu tầm ebook được vài năm, chắc hẳn bạn hiểu rõ cảnh này: một mớ PDF trên Google Drive, EPUB chôn vùi trong thư mục Downloads, vài file MOBI trên chiếc laptop cũ, và một số sách mua trên Amazon mà bạn không thể dễ dàng xuất ra. Không có một nơi duy nhất để duyệt, quản lý, hay gửi bất cứ thứ gì lên Kindle mà không phải chuyển đổi thủ công rồi đính kèm vào email.

Nguyên nhân không phải do lười biếng — mà là vì không có một công cụ tự host nào xử lý gọn hết tất cả những việc đó. Calibre bản desktop rất mạnh nhưng không được thiết kế cho truy cập từ xa hay dùng trên nhiều thiết bị. Calibre-Web lấp đầy khoảng trống đó. Đây là giao diện web cho thư viện Calibre của bạn — chạy trong container, truy cập được từ mọi trình duyệt hoặc Kindle, và hỗ trợ luồng email “Send to Kindle” chính thức của Amazon.

Mình đã chạy cái này trong homelab hơn một năm rồi. Một khi cấu hình xong, bạn gần như quên đi sự tồn tại của nó — sách tự xuất hiện trên Kindle khi bạn cần. Tuy nhiên, để cấu hình đúng ngay từ đầu, đặc biệt là phần SMTP để gửi lên Kindle, mình đã phải thử vài lần mới ra. Hướng dẫn này ghi lại đúng những bước thực sự hoạt động.

Cài đặt

Yêu cầu trước khi bắt đầu

Trước khi bắt đầu, hãy đảm bảo bạn có:

  • Docker và Docker Compose đã cài trên server
  • Thư viện Calibre có sẵn (file metadata.db và các file sách), hoặc một thư mục trống nếu bạn bắt đầu từ đầu
  • Tài khoản Gmail (hoặc bất kỳ SMTP provider nào) để dùng tính năng gửi email lên Kindle
  • Địa chỉ email @kindle.com của Kindle trong cài đặt tài khoản Amazon của bạn

Cấu trúc thư mục

Tạo các thư mục trước. Điều này giúp mọi thứ gọn gàng và dễ backup:

mkdir -p ~/homelab/calibre-web/config
mkdir -p ~/homelab/calibre-web/books

Nếu bạn đã có thư viện Calibre, hãy copy hoặc mount thư mục chứa metadata.db vào ~/homelab/calibre-web/books. Thư mục phải chứa file metadata của Calibre, nếu không Calibre-Web sẽ khởi tạo một thư viện trống.

File Docker Compose

Tạo file compose:

nano ~/homelab/calibre-web/docker-compose.yml
version: "3.8"

services:
  calibre-web:
    image: lscr.io/linuxserver/calibre-web:latest
    container_name: calibre-web
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Tokyo
      - DOCKER_MODS=linuxserver/mods:universal-calibre  # bật tính năng chuyển đổi định dạng ebook
    volumes:
      - ./config:/config
      - ./books:/books
    ports:
      - 8083:8083
    restart: unless-stopped

Một vài lưu ý về cấu hình này:

  • PUID/PGID: Chạy lệnh id trong terminal để lấy user ID và group ID thực tế của bạn. Dùng đúng giá trị này tránh lỗi phân quyền trên các volume được mount.
  • DOCKER_MODS: Mod universal-calibre cài toàn bộ binary của Calibre vào trong container. Đây là yêu cầu bắt buộc để chuyển đổi định dạng (ví dụ: EPUB sang MOBI) và để tính năng gửi lên Kindle hoạt động. Nếu thiếu dòng này, nút “Send to Device” sẽ bị xám và không dùng được.
  • Port 8083: Port mặc định của Calibre-Web. Đổi phần bên trái nếu port đó đã được dùng trên host của bạn.

Khởi động container:

cd ~/homelab/calibre-web
docker compose up -d

Lần khởi động đầu tiên mất 2–4 phút trong khi DOCKER_MODS tải và cài Calibre binaries. Theo dõi log để xác nhận quá trình hoàn tất:

docker compose logs -f calibre-web

Chờ cho đến khi thấy dòng [ls.io-init] done. rồi mới tiếp tục.

Cấu hình

Trình hướng dẫn cài đặt ban đầu

Mở trình duyệt và truy cập http://<địa-chỉ-ip-server>:8083. Bạn sẽ thấy màn hình cài đặt ban đầu yêu cầu nhập đường dẫn đến thư viện Calibre.

Đặt đường dẫn database thành /books (đường dẫn trong container, không phải trên host). Nhấn “Submit”. Nếu Calibre-Web tìm thấy metadata.db, nó sẽ tải thư viện ngay lập tức. Nếu không, nó sẽ tạo một thư viện trống mới.

Thông tin đăng nhập mặc định:

  • Tên đăng nhập: admin
  • Mật khẩu: admin123

Đổi mật khẩu ngay sau lần đăng nhập đầu tiên qua Admin → Edit User → admin.

Bật tính năng chuyển đổi định dạng sách

Vào Admin → Edit Basic Configuration → Feature Configuration. Trong phần “External Binaries”, đặt:

  • Path to Calibre Binaries: /usr/bin

Dòng này chỉ cho Calibre-Web biết nơi tìm binary ebook-convert được cài bởi Docker mod. Nếu thiếu, việc chuyển đổi định dạng sẽ âm thầm thất bại — không có thông báo lỗi, sách đơn giản là không đến nơi.

Lưu thay đổi rồi quay lại trang Feature Configuration. Bật:

  • Enable Uploads — cho phép tải sách mới lên qua giao diện web
  • Enable Sending books via email — bắt buộc để gửi sách lên Kindle

Cấu hình SMTP để gửi lên Kindle

Đây là phần mà hầu hết các hướng dẫn thường bỏ qua chi tiết. Hệ thống “Send to Kindle” của Amazon hoạt động bằng cách gửi email kèm file sách đến địa chỉ @kindle.com của Kindle bạn. Calibre-Web tự xử lý việc chuyển đổi và gửi — bạn chỉ cần cung cấp thông tin SMTP hợp lệ.

Vào Admin → Edit Basic Configuration → Email Server Settings và điền:

SMTP Hostname:  smtp.gmail.com
SMTP Port:      587
Encryption:     STARTTLS
SMTP Login:     [email protected]
SMTP Password:  (Mật khẩu ứng dụng — xem bên dưới)
From E-mail:    [email protected]

Quan trọng: Gmail yêu cầu Mật khẩu ứng dụng (App Password), không phải mật khẩu tài khoản thông thường, khi bật xác thực 2 bước. Tạo mật khẩu này tại Tài khoản Google → Bảo mật → Mật khẩu ứng dụng. Chọn “Mail” và “Khác (tên tùy chỉnh)”, đặt tên là “Calibre-Web”, rồi copy mật khẩu 16 ký tự hiển thị ra.

Quay lại trang admin, mở Edit User → admin và nhập địa chỉ Kindle vào trường Kindle E-Mail. Định dạng: tênbạ[email protected]. Tìm địa chỉ này tại Amazon → Tài khoản → Manage Your Content and Devices → Preferences → Personal Document Settings.

Còn một bước nữa dễ bị bỏ sót: Amazon chỉ nhận tài liệu từ các địa chỉ email đã được phê duyệt. Trong tài khoản Amazon, vào Manage Your Content and Devices → Preferences → Personal Document Settings → Approved Personal Document E-mail List. Thêm địa chỉ Gmail bạn đã cấu hình làm địa chỉ gửi SMTP. Bỏ qua bước này và mọi lần gửi sẽ âm thầm thất bại.

Gửi sách lên Kindle

Duyệt đến bất kỳ cuốn sách nào trong thư viện, nhấn vào bìa sách để mở trang chi tiết, rồi nhấn Send to Kindle. Calibre-Web sẽ chuyển đổi sách sang định dạng phù hợp và gửi email đến địa chỉ Kindle của bạn. Sách xuất hiện trên thiết bị sau vài phút khi kết nối WiFi.

Sách đã ở định dạng MOBI hoặc AZW3 sẽ đến gần như ngay lập tức. EPUB cần chuyển đổi trước — thường mất 10–30 giây tùy kích thước file. Một tiểu thuyết 300 trang thông thường (~500 KB EPUB) chuyển đổi xong trong dưới 15 giây.

Kiểm tra & Giám sát

Xác nhận cài đặt hoạt động đúng

Kiểm tra tính năng chuyển đổi bằng cách tải lên một file EPUB nhỏ và thử gửi lên Kindle. Theo dõi log container trong quá trình gửi:

docker compose logs -f calibre-web | grep -i "convert\|mail\|send\|error"

Một lần gửi thành công trông như thế này:

Converted book to mobi format
Mail sent to tênbạ[email protected]

Lỗi xác thực SMTP hầu như luôn có nghĩa là App Password sai hoặc thiếu địa chỉ gửi trong danh sách phê duyệt của Amazon. Nếu thấy “ebook-convert not found”, DOCKER_MODS chưa cài đúng — chạy docker compose down && docker compose up -d và chờ quá trình cài mod hoàn tất.

Lưu log lâu dài

Calibre-Web ghi log vào trong config volume. Xem trực tiếp bằng lệnh:

tail -f ~/homelab/calibre-web/config/calibre-web.log

Với môi trường homelab, mức độ chi tiết log mặc định là ổn. Khi cần debug, vào Admin → Edit Basic Configuration → Logging và tạm thời đặt log level thành DEBUG.

Cập nhật container

Image của LinuxServer thường xuyên có bản cập nhật mới. Thêm vào cron hàng tuần hoặc chạy thủ công:

cd ~/homelab/calibre-web
docker compose pull
docker compose up -d

Dữ liệu thư viện và cấu hình của bạn được lưu trong các volume được mount, nên việc cập nhật không làm mất dữ liệu.

Reverse Proxy (Tùy chọn nhưng nên có)

Để truy cập Calibre-Web từ bên ngoài mạng gia đình, hãy đặt nó sau một reverse proxy có HTTPS. Nginx Proxy Manager hoặc Traefik đều hoạt động tốt — cách cài giống hệt bất kỳ service nào khác trong homelab stack của bạn.

Đừng expose port 8083 trực tiếp ra internet. Nếu không có HTTPS, thông tin đăng nhập của bạn truyền đi dưới dạng plaintext, và trang admin của Calibre-Web cấp quyền truy cập toàn bộ thư viện bao gồm cả upload và xóa.

Lời kết

Calibre-Web chứng minh giá trị của mình rất nhanh. Chỉ riêng tính năng gửi lên Kindle đã xứng đáng với thời gian cài đặt — không còn phải đi tìm file EPUB, chạy qua Calibre desktop, rồi gửi email đính kèm cho chính mình nữa. Thêm sách vào thư viện, nhấn Send, sách có mặt trên thiết bị.

Có hai điểm hay làm người dùng vấp phải: dòng DOCKER_MODS (dễ bỏ sót, âm thầm phá vỡ toàn bộ tính năng chuyển đổi) và danh sách địa chỉ gửi được phê duyệt của Amazon (không được ghi trong tài liệu, không rõ ràng, nhưng bắt buộc phải có). Làm đúng hai điểm đó thì mọi thứ còn lại sẽ không có gì bất ngờ cả.

Mình đã chạy Calibre-Web hơn một năm mà không cần đụng vào nó. Không bảo trì, không sự cố, không cần can thiệp. Đó chính xác là kiểu ổn định đáng nhàm chán mà một service homelab cần hướng tới.

Share: