Install Calibre, Calibre-Web & CWA on Your Server: Your E-Book Management with Docker

Connecting to the Server and Checking/Performing Docker Installation

The first thing we need is a connection to our server. I open a terminal and connect via SSH:

ssh deployn@YOUR_SERVER_IP

Replace deployn with your username and YOUR_SERVER_IP with your server’s IP address. After authentication (confirm with yes if necessary and enter your password), we are connected.

Now, let’s check if Docker and Docker Compose are installed:

docker -v
docker compose version

If Docker is not yet installed, we’ll install it now. For Ubuntu servers (adjust this for your distribution if necessary), this is often done as follows (based on the official Docker documentation):

1. Set up Docker’s Apt repository:

   # Add Docker's official GPG key:
   sudo apt-get update
   sudo apt-get install ca-certificates curl
   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc
   
   # Add the repository to Apt sources:
   echo \
     "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
     $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
     sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   sudo apt-get update

2. Install Docker Engine, CLI, Containerd, and Docker Compose Plugin:

   sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

After installation, let’s check the versions again:

docker -v
# Expected output (Example): Docker version 28.1.1, build ...
docker compose version
# Expected output (Example): Docker Compose version v2.25.1

Optionally, we can update the entire system:

sudo apt update && sudo apt upgrade -y

Install Calibre with Docker (LinuxServer.io Image)

We will use the popular Docker image from LinuxServer.io for Calibre.

1. Create folder: We create a folder for our Calibre configuration.

   mkdir calibre
   cd calibre

2. Create docker-compose.yml: Create a file named docker-compose.yml.

   nano docker-compose.yml

3. Insert and customize content: Copy the following configuration into it and adjust it.

   services:
     calibre:
       image: lscr.io/linuxserver/calibre:latest
       container_name: calibre
       security_opt:
         - seccomp:unconfined #optional
       environment:
         - PUID=1000 # Your User ID
         - PGID=1000 # Your Group ID
         - TZ=Europe/Berlin # Your Timezone
         - PASSWORD=asdfasdf # Choose a SECURE password! This is just an insecure example.
         - CLI_ARGS= # Optional: Additional Calibre CLI arguments
       volumes:
         - ./config:/config # Path to configuration and library on the host
       ports:
         - 8080:8080 # GUI access
         - 8081:8081 # Calibre Server (optional)
       restart: unless-stopped

4. Important customizations:

   • PUID/PGID: Check your user and group ID using the id command in the terminal on your server and adjust PUID and PGID accordingly (it’s often 1000).
   • TZ: Set your correct time zone (e.g., America/New_York, Europe/London).
   • PASSWORD: You absolutely must change asdfasdf to a strong, secure password! This password is required to access the Calibre GUI via the browser.
   • Volumes: ./config:/config means that a subfolder named config will be created in the current directory (calibre) (if it doesn’t already exist), where Calibre will store its configuration and the e-book library. Ensure paths like this (./config) are relative to where you save your docker-compose.yml file.

5. Create configuration folder (if necessary): Since we mapped ./config, let’s ensure this folder exists:

   mkdir config

6. Start the container:

   sudo docker compose up -d

   Docker will now download the Calibre image (this can take a while, it’s quite large) and start the container in the background (-d).

Calibre – The First Test (and the Pitfalls)

After starting, we can check the resource usage:

# General system load
htop

# Docker container specific
sudo docker stats

# View logs (Ctrl+C to exit)
sudo docker compose logs -f

In my case, Calibre consumed about 360 MB of RAM right after starting. The logs should not show any serious errors.

Now let’s try to access the web interface: Open your browser and enter http://YOUR_SERVER_IP:8080.

You should be prompted to log in:

• Username: abc (default user if not configured otherwise)
• Password: The password you set in the docker-compose.yml (e.g., asdfasdf - hopefully you chose a better one!).

After successful login, the Calibre setup wizard starts:

1. Select the library location (the default /config inside the container is correct since we mapped this folder).
2. Optional: Select your e-book reader.
3. Complete the setup.

Calibre now starts its full desktop interface in the browser. You’ll see an empty library and possibly a “Quick Start Guide”.

Performance Warning: In my test, opening the book led to very high CPU and RAM usage, which overwhelmed my small test server and made it temporarily unreachable. A server restart (sudo reboot) was necessary. The full Calibre GUI via Web VNC is very resource-intensive! For pure reading and management tasks, this is often not the ideal solution.

However, the most important part of this step was that Calibre created the library structure in the mapped ./config folder, especially the metadata.db file.

# In the 'calibre' folder on the host:
ls config/
# Should show 'Calibre Library' among others
ls config/'Calibre Library'/
# Should show 'metadata.db' among others

Calibre-Web – The Lightweight Alternative

Since the full Calibre GUI is too cumbersome, we stop the Calibre container and install Calibre-Web instead. This is a lean web application that accesses the metadata.db created by Calibre.

1. Stop the Calibre container:

   # Make sure we are in the 'calibre' folder
   cd /path/to/your/calibre-folder
   sudo docker compose down

2. Create docker-compose-calibre-web.yml: We create a new Compose file for Calibre-Web to keep the configurations separate. Assume this file is also created within the main calibre folder for simplicity in path examples below, or adjust paths accordingly.

   nano docker-compose-calibre-web.yml

3. Insert and customize content:

   services:
     calibre-web:
       image: lscr.io/linuxserver/calibre-web:latest
       container_name: calibre-web
       environment:
         - PUID=1000 # Your User ID
         - PGID=1000 # Your Group ID
         - TZ=Europe/Berlin # Your Timezone
         - DOCKER_MODS=linuxserver/mods:calibre-web-update-calibre # Optional: Enables in-app updates for Calibre metadata tools
         - OAUTHLIB_RELAX_TOKEN_SCOPE=1 # Optional: Needed for certain OAuth logins
       volumes:
         - ./calibre-web-config:/config # New folder for Calibre-Web configuration
         - ./config:/books # Path to the folder containing the existing Calibre Library!
       ports:
         - 8083:8083 # Port for Calibre-Web
       restart: unless-stopped

4. Important customizations:

   • PUID/PGID/TZ: Adjust as with Calibre.
   • Volumes:
     • ./calibre-web-config:/config: This is where Calibre-Web stores its own configuration. We need to create this folder relative to the compose file: mkdir calibre-web-config.
     • ./config:/books: This is the crucial point! We map the host folder (./config) that contains the Calibre Library folder (created by Calibre earlier) to /books inside the Calibre-Web container. This allows Calibre-Web to find the library within /books. Ensure ./config is the correct relative path from your docker-compose-calibre-web.yml to the directory holding Calibre Library.
   • Ports: We use port 8083, as 8080 might be used by other services (or just for clear separation).

5. Start the container:

   sudo docker compose -f docker-compose-calibre-web.yml up -d

   The Calibre-Web image is significantly smaller and starts faster.

Calibre-Web – Configuration and Usage

1. Access: Open http://YOUR_SERVER_IP:8083.
2. First Login: The default credentials are:
   • Username: admin
   • Password: admin123
3. Configure Database Path: After logging in, you will be prompted to specify the path to the Calibre database. Click the button to select, navigate within the container to the /books folder (which we mapped), and inside that folder, select the actual library directory (usually named Calibre Library). Click “Save”.
4. Change Password: Go immediately to Admin Settings -> Manage Users -> Select admin and change the default password admin123 to a secure password!
5. Enable Uploads (optional):
   • Go to Admin -> Edit Basic Configuration -> Feature Configuration.
   • Check the box for Enable Uploads. Save.
   • Go back to Admin -> Manage Users -> Select admin.
   • Check the box for Allow Uploads. Save.
   • An upload button should now appear in the top right.

Now you can see your library (including the Quick Start Guide, if it’s still there). You can upload books:

• Individual files: Click “Upload” and select a file (e.g., EPUB, PDF).
• Add more formats to a book: Open a book, go to “Edit metadata” -> “Add book format” and upload other formats (PDF, MOBI, etc.) there. This associates them with the same book entry. (Otherwise, uploading multiple files directly might recognize them as separate books).

Calibre-Web is significantly more resource-efficient than the full Calibre GUI and offers a good web interface for reading and management.

CWA (Calibre-Web Automated) – The Modern Fork

CWA is a fork of Calibre-Web with some additional features and a slightly more modern approach, e.g., for automatically processing books in a “watch” folder.

1. Create a new folder: We create a separate directory for CWA.

   cd .. # Go back to the parent directory
   mkdir cwa
   cd cwa

2. Create required folders:

   mkdir config # For CWA configuration
   mkdir books  # The "watch" folder for new books
   # The actual library folder is managed by CWA within 'config' or a separate mapping. In the example below, we use a separate mapping.
   mkdir library # CWA will store the structured library here

3. Create docker-compose.yml:

   nano docker-compose.yml

4. Insert and customize content (Example based on Crocodilestick):

   services:
     calibre-web-automated:
       image: crocodilestick/calibre-web-automated:latest # Verify this is the image you intend to use
       container_name: cwa
       environment:
         - PUID=1000 # Your User ID
         - PGID=1000 # Your Group ID
         - TZ=Europe/Berlin # Your Timezone
       volumes:
         - ./config:/config             # CWA configuration data
         - ./library:/calibre-library   # CWA library is stored here
         - ./books:/cwa-book-ingest     # The "watch" folder for new uploads
       ports:
         - 8084:8083 # Port for CWA (we use 8084 as 8083 is taken by Calibre-Web)
       restart: unless-stopped

5. Important customizations:

   • PUID/PGID/TZ: Adjust as before.
   • Volumes:
     • ./config:/config: CWA-specific configuration files.
     • ./library:/calibre-library: This is where CWA stores the processed books in a Calibre-like structure on the host.
     • ./books:/cwa-book-ingest: Books copied to this folder on the host should be automatically detected by CWA and imported into the library located at /calibre-library inside the container (this behavior is configurable within CWA).
   • Ports: We change the host port to 8084 to avoid conflicts.

6. Start the container:

   sudo docker compose up -d

CWA – Configuration and Usage

1. Access: Open http://YOUR_SERVER_IP:8084.
2. First Login: Default is the same as Calibre-Web:
   • Username: admin
   • Password: admin123
3. Configure Database Path: CWA should automatically detect that no database exists yet and offer to create a new one. It should default to using the mapped /calibre-library volume. If prompted for the library path, ensure /calibre-library is selected, as this is the path inside the container that we mapped.
4. Change Password: Again: Immediately go to Settings -> Manage Users and change the admin password!
5. Usage:
   • The interface resembles Calibre-Web (you can also switch to the light theme).
   • Uploads are often enabled by default.
   • You can upload books or place files in the mapped ./books folder on the host; CWA should process them (check CWA settings for ingest configuration).
   • CWA has extended converter options and metadata search features.
   • Adding multiple formats to one book is done similarly to Calibre-Web via “Edit Metadata” -> “Upload another format”.
   • CWA tends to consume slightly more RAM than standard Calibre-Web.

Important Note: Backup!

Regardless of whether you use Calibre-Web or CWA, your valuable e-books are now located in the mapped folders on your host system!

• For Calibre-Web: The books are in the Calibre Library folder created by the initial Calibre setup (likely located within the first ./config directory relative to the Calibre docker-compose.yml). Calibre-Web’s own configuration is in the ./calibre-web-config folder (relative to the Calibre-Web docker-compose-calibre-web.yml). Back up the library folder (path/to/calibre/config/Calibre Library) and the Calibre-Web config folder (path/to/calibre-web/calibre-web-config) regularly! Adjust paths based on your actual folder structure.
• For CWA: The books are in the ./cwa/library folder. The configuration is in ./cwa/config. The upload folder is ./cwa/books. Back up at least the library and config folders (relative to the CWA docker-compose.yml).

Outlook: Reverse Proxy & More

To make your Calibre-Web or CWA instance securely and conveniently accessible via a domain (e.g., ebooks.your-domain.com), you should use a reverse proxy like Nginx Proxy Manager, Traefik, or Caddy. This enables HTTPS and hides the ports.

If you don’t have a fixed public IPv4 address, solutions like Cloudflare Tunnels or Tailscale could be interesting. [Replace with the tool you discussed, e.g., “Pangolin” if that’s a specific project name].

Conclusion

With Docker, you can run Calibre, Calibre-Web, or CWA relatively easily on your server. While the full Calibre GUI is very resource-intensive, Calibre-Web and CWA offer excellent, lightweight alternatives for managing and accessing your e-book library via the browser. Choose the solution that best suits your needs and server performance.

I hope you enjoyed this tutorial.