VPS Tutorials
Ebook Server on VPS: Kavita, Calibre-Web, OPDS and Backups (2026)
Choose Kavita, Calibre-Web or Komga, prepare library metadata and permissions, protect first setup and HTTPS, connect OPDS readers and verify consistent backups.

An ebook server gives compatible devices a shared library and, where supported, synchronized reading progress. It complements the site's music, video and photo guides. Start with readable files you are entitled to store: DRM, format support and device restrictions do not disappear merely because you self-host.
This guide compares Calibre-Web, Kavita and Komga, then gives both Kavita and Calibre-Web deployment paths. It does not assume a particular language, country or metadata catalog.
| Option | Best starting point | Important conditions |
|---|---|---|
| Calibre-Web | An existing Calibre-managed ebook library | Requires Calibre database; conversion, email delivery and Kobo integration need their own configuration |
| Kavita | Books and comics organized for its supported scanner | No Calibre database; check current format, reader and metadata features |
| Komga | Comic-focused collections | Check supported formats, device integration and JVM resources |
EPUB reading, comic CBZ/CBR support, Kobo compatibility and conversion differ by release; test representative files. Calibre tools provide broad conversion support (the original described 50+ formats), but not every conversion preserves layout or defeats DRM. Original idle-memory figures of 80 MB, 150–250 MB and 150 MB+ and GitHub counts 16.7k/10.1k/6k were snapshots, not current performance or quality rankings.
- Already manage books in Calibre: consider Calibre-Web.
- Start with mixed loose books/comics: consider Kavita.
- Mostly comics: consider Komga.
Calibre-Web needs metadata.db, not just a directory of EPUB files.
| Files | Example per file | Original 1000-file budget |
|---|---|---|
| Text EPUB | 1–5 MB | 3–5 GB |
| Scanned PDF | 20–100 MB | 30–80 GB |
| Comic CBZ | 50–200 MB | 100 GB+ |
Measure your collection: these totals are illustrative, not exact multiplication or guaranteed compression. Around 20 GB may suit a small text library; comics/PDFs often justify 100 GB or more, plus databases, thumbnails and backups. A 1 vCPU/2 GB server is a useful initial budget; 1 GB may work for light Kavita use but first scans and other services can need more. Thumbnail generation on thousands of files can take tens of minutes and consume CPU/I/O.
books/
├── 刘慈欣/
│ ├── 三体.epub
│ ├── 三体Ⅱ·黑暗森林.epub
│ └── 球状闪电.epub
├── 阿西莫夫/
│ └── 基地.epub
└── 漫画/
└── 进击的巨人/
├── 第01卷.cbz
└── 第02卷.cbz
- Organize books into deliberate subdirectories, with each author/series grouping checked in the scanner.
- Avoid an untested pile of files at the library root; follow rules for the selected format and library type.
- Use author or series names where helpful, but do not assume every top-level directory is always a series: EPUB metadata can determine grouping.
Before bulk renaming, back up filenames and test a few files. Unicode or Chinese names are not universally invalid; preserve meaningful titles and avoid collisions.
- Check bracket parsing: the original examples are
三体(一).epub,三体_I.epuband三体1.epub. - Check symbols
★/【】and emoji with the actual parser. - Check volume marks such as
①②/Ⅲbefore changing them.
For UnauthorizedAccessException, inspect actual container UID/GID and parent-directory access. Verify before using the example ownership change; UID 1001 is not guaranteed across all images/releases, and recursive changes affect the library:
sudo chown -R 1001:1001 ~/ebooks/books
Grant only needed read/write access; use a read-only books mount when uploads/metadata writes are unnecessary.
mkdir -p ~/ebooks/{config,books}
cd ~/ebooks
Create docker-compose.yml:
services:
kavita:
image: jvmilazz0/kavita:latest
container_name: kavita
restart: unless-stopped
environment:
- TZ=Asia/Shanghai
ports:
- "127.0.0.1:5000:5000"
volumes:
- ./config:/kavita/config
- ./books:/books
Use a reviewed image/version. Keep /kavita/config as the demonstrated container config destination; its host-side directory can change with the mapping. It holds SQLite and user/settings state and needs backup.
Bind to 127.0.0.1. Complete first-user setup through a private tunnel before exposing the proxy, so another visitor cannot create the administrator. PUID/PGID are image-specific, not universal controls. Use chown only after verifying the image's effective identity. Choose timezone for your deployment; Asia/Shanghai in the example is not a localization requirement.
docker compose up -d
docker compose logs -f
Reach http://你的IP:5000 through the appropriate local tunnel and create a unique administrator credential.
Open Server Settings → Libraries → Add Library, adapting labels to your version. Book suits prose, while Manga/Comic have comic-reader conventions such as reading direction. Point to /books, a container path.
For separate reading settings, mount and register novels and comics separately:
volumes:
- ./config:/kavita/config
- ./novels:/novels
- ./comics:/comics
Wait for the initial scan, inspect a few groupings and rescan after corrections. Do not infer recursive classification behavior without checking your version.
Start with embedded EPUB metadata/ComicInfo and manual edits. The original named ComicVine, AniList, MyAnimeList and Google Books; actual enrichment support can depend on integrations, accounts and service tiers. It is not a promise that base Kavita automatically queries all of them.
- Verify automatic matches for every language and edition.
- For Chinese-language works, the original notes poor matching and no assumed Douban integration; retain that regional/catalog condition instead of promising global coverage.
- Edit title, author, description and cover manually, or accept useful filenames where metadata is unavailable.
Good organization remains useful even without automatic enrichment.
/books must contain a complete Calibre library including metadata.db. Copy the database and associated book directories, with writers stopped during the transfer:
rsync -av ~/Calibre\ 书库/ user@server:~/ebooks/library/
If none exists, create one with desktop Calibre, add a book and transfer it. calibredb is a command family to consult in the installed Calibre documentation, not a complete empty-library initialization procedure by itself.
Create docker-compose.yml:
services:
calibre-web:
image: lscr.io/linuxserver/calibre-web:latest
container_name: calibre-web
restart: unless-stopped
environment:
- PUID=1000
- PGID=1000
- TZ=Asia/Shanghai
- DOCKER_MODS=linuxserver/mods:universal-calibre
volumes:
- ./config:/config
- ./library:/books
ports:
- "127.0.0.1:8083:8083"
Match PUID/PGID to intended file ownership, checking id -u/id -g. Use separate config directories/projects if running both products; their ./config examples should not share application state accidentally.
DOCKER_MODS adds conversion tools where that image/mod supports them. Installation can take the original 2–5-minute example or longer; review resource usage and dependencies. Kindle delivery must use currently accepted formats: the original EPUB-to-MOBI email advice is outdated, while Send to Kindle supports EPUB under its current requirements.
Complete setup privately at http://你的IP:8083. The original default admin/admin123 must be replaced before public access; verify actual defaults for the installed version. In Admin → Basic Configuration set database location to /books, the container path.
Never let desktop Calibre and Calibre-Web write the same metadata.db simultaneously. Use one writer and consistent transfers/backups to avoid SQLite/library corruption.
- HTTPS provides the secure context required by some clipboard/PWA browser features.
- It protects credentials while reading over public Wi-Fi and other untrusted networks.
- Caddy automates certificates when DNS and validation challenges are correctly configured.
Configure the Kavita proxy:
books.example.com {
encode gzip
reverse_proxy 127.0.0.1:5000
}
For Calibre-Web, substitute its private upstream port. reverse_proxy handles WebSocket upgrades in Caddy. The following Nginx fragment belongs in a complete appropriate proxy configuration:
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header X-Forwarded-Proto $scheme;
client_max_body_size 2000m;
Forward scheme with X-Forwarded-Proto and review Base URL/trusted-proxy settings. client_max_body_size changes upload limits; the shown 2000m is a large example, not a required safe default. Match uploads to disk, proxy and application capacity. See Caddy proxy guidance.
- Kavita provides a per-user endpoint such as
https://books.example.com/api/opds/你的API密钥. - Calibre-Web exposes
https://books.example.com/opdsunder its configured access rules.
Treat API-key URLs as credentials. Verify OPDS, TLS, authentication and format support in clients such as KOReader, Moon+ Reader, KyBook or Panels; do not assume every app/device/version supports the same functions. E-ink browsers and stock Kindle/Kobo firmware have distinct limitations.
Kavita's browser/PWA experience may support Add to Home Screen and progress sync on compatible devices. For Calibre-Web:
- Send to Kindle needs SMTP, allowed-sender/device settings and currently supported files. Gmail app passwords require eligible account/security settings; do not assume the ordinary login password works.
- Kobo integration depends on device firmware and its documented API/synchronization setup; verify progress behavior, not only book downloads.
Use a reader account with limited library access instead of distributing administrator credentials.
Preserve both content and configuration, including users, metadata and progress. Stop writers for a consistent SQLite backup:
cd ~/ebooks
docker compose stop
tar czf ~/ebooks-backup-$(date +%F).tar.gz config books
docker compose start
For the Calibre-Web variant, include its library directory too: the sample's books path alone misses it. Check archive success and restart after failures. Large collections can use rsync for incremental transfers plus consistent config snapshots; remote/object storage needs a transfer tool appropriate to its interface. A rclone mount alone is not a completed backup: verify uploads, independent retention and a restore drill.
Missing books: check grouping/scanner rules, permissions with chown 1001:1001, mount paths and correct library type; test a representative file.
Blank covers: inspect embedded metadata and actual provider integration. Manually upload or use Calibre ebook-meta on a backed-up library with other writers stopped; Chinese catalog coverage can be incomplete.
Reader spins on a large PDF: browser/mobile rendering can exhaust memory. Download through supported OPDS and read locally if practical.
Kavita redirect loop: inspect X-Forwarded-Proto, external scheme and Base URL, including any extra proxy.
DB Location is not valid: /books must contain metadata.db and the complete accessible library, not loose EPUBs.
Uploads do not appear: check Calibre-Web Allow Uploads and user/filesystem permissions; Kavita may need Rescan. A read-only mount cannot accept uploads.
Disk full: inspect du -sh books/*, thumbnails, comics/PDFs and backups. Archive intentionally and verify remote availability rather than deleting the only copy.
Self-hosting offers control over readable files and your organization, not an unconditional ownership or DRM guarantee. Subscription prices are region-dependent. Choose by whether you already have a Calibre library and test the directory/metadata rules before importing the full collection.