Calibre-Web eBook Library: Host Your Digital Bookshelf in Docker

Self-hosting Calibre-Web on a Virtual Private Server (VPS) via Docker Compose provides a lightweight, responsive interface to manage, read, and share your digital book collection. Unlike the full desktop Calibre package, Calibre-Web uses an existing Calibre database structure to serve books through a modern web UI, offering features like OPDS feeds for mobile reader integration and direct SMTP delivery to e-readers (such as Kindle).

Directory Structure and Permissions Setup

Before deploying the container, you must configure a consistent directory layout and resolve file ownership permissions. Calibre-Web requires write access to the SQLite database (metadata.db) and the directories containing the book files.

Run the following commands on your VPS to build the directory structure:

mkdir -p ~/calibre-web/{config,books}

Identify the user ID (UID) and group ID (GID) of the system user running the Docker daemon. This prevents permission conflicts between the host filesystem and the container:

id $USER

Note the values for uid (typically 1000) and gid (typically 1000). These will be passed as environment variables in the Docker Compose file.

Docker Compose Configuration

The deployment uses the official image maintained by LinuxServer.io. Create the docker-compose.yml file:

nano ~/calibre-web/docker-compose.yml

Insert the following configuration:

version: '3.8'

services:
  calibre-web:
    image: lscr.io/linuxserver/calibre-web:latest
    container_name: calibre-web
    environment:
      - PUID=1000  # Replace with host UID from 'id' command
      - PGID=1000  # Replace with host GID from 'id' command
      - TZ=UTC
      - DOCKER_MODS=linuxserver/mods:universal-calibre  # Optional: Adds calibre utilities for ebook format conversion
    volumes:
      - ./config:/config
      - ./books:/books
    ports:
      - 8083:8083
    restart: unless-stopped

Environment Variable & Volume Details

• PUID/PGID: Ensures the container writes files back to the host filesystem with your user's permissions, making manual uploads or syncing via rsync/sftp seamless.
• DOCKER_MODS=linuxserver/mods:universal-calibre: Installs Calibre command-line utilities within the container. This is crucial for enabling on-the-fly eBook conversion (e.g., converting .epub to .mobi or .pdf for Kindle compatibility).
• ./books: This directory must map to the path containing your metadata.db and folder hierarchy.

First-Time Database Initialization

Calibre-Web does not generate a database from scratch; it requires an existing Calibre structure. If you are migrating a desktop library, copy your existing library folder containing metadata.db directly into the ./books directory.

If starting a brand-new library, you must provide an empty Calibre SQLite database. You can acquire an empty template metadata.db by: 1. Copying it from a clean desktop Calibre installation. 2. Downloading an empty template database.

Place the metadata.db file in the base of the mapped ./books directory on your host:

ls -la ~/calibre-web/books/
# Expected output should list metadata.db along with subdirectories for authors/books

Set the proper file permissions on the database before booting the stack:

chown -R 1000:1000 ~/calibre-web/books
chmod 664 ~/calibre-web/books/metadata.db

Launch the service:

cd ~/calibre-web
docker compose up -d

Confirm that the application is running:

docker compose logs -f

Reverse Proxy Integration

For secure external access (HTTPS), route traffic through a reverse proxy. Below are configurations for both Caddy and Nginx.

Option A: Caddy Configuration

Caddy handles automatic SSL certificate provisioning and renewal natively. Add the following to your Caddyfile:

books.yourdomain.com {
    reverse_proxy localhost:8083 {
        # Increase body limit for large PDF/EPUB uploads
        request_body_limit 500MiB
    }
}

Option B: Nginx Configuration

Create an Nginx server block config (/etc/nginx/sites-available/calibre-web):

server {
    listen 80;
    server_name books.yourdomain.com;
    client_max_body_size 500M; # Essential for uploading large book archives

    location / {
        proxy_pass http://127.0.0.1:8083;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Disable buffering to allow smooth rendering of in-browser reader
        proxy_buffering off;
    }
}

Apply Certbot to Nginx to secure the connection:

sudo certbot --nginx -d books.yourdomain.com

OPDS Configuration and Mobile Reader Access

The Open Publication Distribution System (OPDS) is an XML-based syndication format for digital publications. Enabling OPDS allows mobile reader apps (like KyBook, Marvin, Moon+ Reader, or Aldiko) to browse, search, and download books directly from your VPS.

1. Enable OPDS in Calibre-Web

1. Log in to the web interface using the default credentials:
2. Username: admin
3. Password: admin123
4. Change the default administrator password immediately under User Profile.
5. Navigate to Admin -> Edit Basic Configuration -> Feature Configuration.
6. Check Enable OPDS Feed.
7. Save settings.

2. Connect Your Mobile Device

Within your mobile reader app, add a new catalog or catalog source using the following URL structure:

https://books.yourdomain.com/opds

The app will prompt you for your Calibre-Web username and password. Once authenticated, you can search and read directly on your device.

Email Integration and Send-to-Kindle Setup

Calibre-Web supports direct SMTP integration to forward eBooks to designated email addresses (e.g., your @kindle.com address).

1. Configure SMTP Server settings

In Calibre-Web, navigate to Admin -> Edit Basic Configuration -> E-Mail Server Settings:

• SMTP Hostname: The SMTP server of your provider (e.g., smtp.gmail.com, smtp.sendgrid.net).
• SMTP Port: 465 (SSL) or 587 (STARTTLS).
• SMTP Encryption: SSL/TLS or STARTTLS.
• SMTP Login: Your email address.
• SMTP Password: Your email password (use an App Password if using Gmail or Microsoft accounts).
• From E-mail: The sender address verified by your SMTP provider.

2. Whitelist Sender in Amazon Kindle Settings

1. Log in to your Amazon account.
2. Go to Manage Your Content and Devices -> Preferences.
3. Scroll down to Personal Document Settings.
4. Under Approved Personal Document E-mail List, add the From E-mail address configured in your Calibre-Web SMTP settings.

3. Add Kindle Address to User Profile

In Calibre-Web, click on your username in the top right to edit your profile, locate the Kindle E-Mail field, and enter your Kindle address (e.g., yourname@kindle.com). Click "Save". A "Send to Kindle" button will now appear on all eligible book detail pages.

Automated Backup Strategy

To prevent data loss, create a crontab task on your VPS to periodically back up the SQLite database and metadata storage directories.

Create a backup script:

nano ~/calibre-web/backup.sh

Add the backup routine, which compresses the configuration files and the main database while ignoring the heavy eBook files if storage is limited on the backup target (or includes them by adjusting paths):

#!/bin/bash
BACKUP_DIR="/opt/backups/calibre-web"
DATE=$(date +%Y-%m-%d_%H%M%S)

mkdir -p "$BACKUP_DIR"

# Stop container to prevent database writes during backup
docker compose -f /home/$USER/calibre-web/docker-compose.yml stop

# Backup database and config
tar -czf "$BACKUP_DIR/calibre_meta_$DATE.tar.gz" -C /home/$USER/calibre-web config books/metadata.db

# Restart container
docker compose -f /home/$USER/calibre-web/docker-compose.yml start

# Keep only the last 30 days of backups
find "$BACKUP_DIR" -type f -name "*.tar.gz" -mtime +30 -delete

Make the script executable and schedule it via cron:

chmod +x ~/calibre-web/backup.sh
crontab -e

Add the following entry to execute the script daily at 2:00 AM:

0 2 * * * /bin/bash /home/youruser/calibre-web/backup.sh >/dev/null 2>&1