Ansible + Docker deployment for calibre-web
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Brian Salcedo ee5332b791 add HSTS headers labels 4 months ago
apps add HSTS headers labels 4 months ago
playbooks remove remote_user leftover from AWS stack 4 months ago
.gitignore initial commit 4 months ago
README.md add HSTS headers labels 4 months ago
Vagrantfile initial commit 4 months ago
inventory initial commit 4 months ago

README.md

Ansible + Docker deployment for calibre-web

This repository contains Ansible playbooks and Docker Compose files for deploying calibre-web on a Debian 9 Linux server. It uses Traefik for the frontend and automatic Letsencrypt certificate management. This stack can be expanded to include more apps, as detailed at the end of this readme.

Prerequisites

  1. Install Ansible on your local machine.
  2. Install Debian 9 (stretch) on a VPS of your choice.
  3. Configure ssh access with public key authentication for Ansible.
  4. Confirm that you are able to ssh into your server.
  5. Configure your DNS.

Quick Start

Note: In this configuration, Traefik uses ACME HTTP challenge to obtain certificates. The desired DNS record for your calibre-web install MUST be created and resolve to your server IP address before doing these steps!

1. Edit the configuration

Edit the following files to suit your installation:

File Description
inventory The Ansible inventory file
apps/calibre-web/.env Holds the FQDN of your calibre-web installation
playbooks/roles/site/files/traefik.toml Traefik configuration

inventory: Set the IP or hostname of your VPS in this file.

apps/calibre-web/.env: This file contains an environment variable CALIBRE_HOST. Set it to the host or domain you wish to serve calibre-web on (e.g. calibre.example.com)

playbooks/roles/site/files/traefik.toml: Traefik configuration. Everything is set here except for your email address for obtaining certificates through Letsencrypt. change your_email@example.com to your email address.

2. Run Ansible

$ ansible-playbook -i inventory playbooks/main.yml

3. Copy your ebooks to your server

Books to be imported into calibre-web are placed in /srv/calibre/books, owned by user www-data. Before the final steps, place your books there and set the correct permissions:

  1. scp -r mybooks root@myserver:/srv/calibre/books
  2. ssh into your server, then sudo chown -R www-data: /srv/calibre/books

4. Configure and sign in to calibre-web

  1. Point your browser to the hostname/domain name you set in the previous steps.
  2. Under Basic Configuration, Set the Location of Calibre Database to /books
  3. Leave Server Port and SSL file locations as the defaults.
  4. Change any additional settings to suit your needs.
  5. Submit the configuration.
  6. The default login is admin, password admin123

Additional notes

Adding more applications can be done by first adding a subdirectory in apps/ and placing a docker-compose.yml with valid syntax in it. Running Ansible again will then pick up your new app and start the services outlined in your compose file. See the existing compose files as a starting point, and the compose file reference.

Traefik relies on Docker container labels to pass frontend rules that specify how it shall connect to your backend applications. These labels are set in the docker-compose.yml files under the labels: key. See the documentation on Traefik frontend rules for more information about how these work.

Letsencrypt certificates are handled automatically by Traefik. Remember: When using ACME HTTP challenge, your domain name must already point to your server so Traefik can complete the challenge and get a valid certificate. This challenge occurs when Traefik sees a container with labels for a domain or subdomain it has not yet seen. Obtained certificates are stored in a file named acme.json in a docker named-volume app_traefik mounted at /data in the running container. You will most likely never have to interact with this file directly.

Renewal of certificates: done automatically when they are due for expiration.

A Vagrantfile is included that will call the Ansible playbooks for provisioning. See playbooks/roles/site/files/traefik-nontls.toml for an HTTP-only Traefik config that can be used for further development and local testing.

Additional security headers for apps: Traefik can set arbitrary headers. It also has predefined labels for setting commonly used security headers: https://docs.traefik.io/configuration/backends/docker/#security-headers See apps/calibre-web/docker-compose.yml for an example of sending HSTS. These are commented out by default.