Calibre-Web Deployment - Role Overview

This page documents the Calibre-Web Docker deployment using Ansible, illustrating the workflow, architecture, and best practices for deploying this containerized application with version control, persistent storage, and optional network-mounted backups.

1. Overview

Calibre-Web is deployed in a Docker container using Ansible. The workflow is consistent with other containerized applications in the lab:

Stop existing container safely
Prepare persistent configuration and backup directories
Deploy templated Docker Compose files using Ansible
Pin the Docker image version to ensure reproducibility
Start the container

This ensures predictable deployments, persistent storage, and automated provisioning.

2. Persistent Configuration and Backups

A host directory is mounted inside the container to hold:

Application configuration files (/config/calibreweb)
Backup files (/nfs/backups/calibre)

Example variables from the role:

calibreweb_setup_config_dir: "/config/calibreweb"
calibreweb_setup_backups_dir: "/nfs/backups/calibre"
calibreweb_setup_backup_filename: "{{ calibreweb_setup_backup_prefix }}{{ ansible_date_time.date }}.sqlc"

Directories are created and owned by a dedicated system user
Ensures the container can read/write configuration and backup files
Supports network-mounted storage for centralizing backups

3. Docker Image Version Control

The deployment uses a specific Docker image version, avoiding automatic latest pulls:

calibreweb_setup_version: 0.6.25
calibreweb_setup_docker_image_name: "calibre-web:{{ calibreweb_setup_version }}"

This ensures reproducible deployments and prevents unexpected changes from upstream image updates.

4. Deployment Workflow

The sequence for deploying Calibre-Web is:

Stop and remove existing container

docker stop calibreweb
docker rm calibreweb
docker network prune -f

Ensure persistent directories exist

mkdir -p 
mkdir -p 
chown <user>:<group> 

Copy templated Docker Compose file
```
docker-compose.yml
```
Prune unused images (optional)
```
docker image prune -f
```

Start the container

docker-compose -f /docker-compose.yml up -d

5. Architecture Diagram

           ┌───────────────────────────┐
           │ Host / Docker Environment │
           │                           │
           │ ┌──────────────────────┐  │
           │ │ Calibre-Web Container│  │
           │ │ - Pinned Image       │  │
           │ │ - Config & Backup    │  │
           │ │ - Exposed Port 8083  │  │
           │ └──────────────────────┘  │
           │                           │
           └─────────────▲─────────────┘
                         │ Access
           ┌─────────────┴─────────────┐
           │ Users / Clients           │
           │ Web Browser / API         │
           └───────────────────────────┘

Config directory is mounted as /config
Backup folder can optionally reside on NFS for centralized storage
The container exposes port 8083 for web access

6. Key Features

Fully automated deployment via Ansible
Persistent configuration and backups
Version-controlled Docker image
Easy integration with other home lab services
Reusable workflow applicable to other containerized applications

7. Best Practices

Pin Docker image versions for reproducibility
Mount host directories for configuration and backup persistence
Prune unused Docker images periodically to conserve disk space
Use templated Docker Compose files for consistency
Automate deployment using Ansible for repeatability

8. Summary

This role demonstrates a robust approach to deploying Calibre-Web using Docker and Ansible, ensuring:

Predictable, reproducible deployments
Persistent storage for configs and backups
Minimal manual intervention
A workflow easily adaptable for other home lab applications

The workflow mirrors the general Docker deployment strategy used in other roles, making it a cornerstone of home lab container management.