Install Calibre OPDS PHP Server (COPS) on Debian

COPS is a Web application allowing the publishing of a Calibre e-books library as a OPDS catalog (Open Publication Distribution System). It allow to easily download e-books from a Calibre library on a e-reader supporting the OPDS format.

This howto is tested on:

• Debian 10.0 Buster

This howto is tested with these software’s versions:

• 1.1.3

Requirements

This howto requires :

• biapy-downloader, for downloading the software’s latest versions.
• a2tools, command-line tool easing Apache 2 configuration.
• a HTTP server with PHP support, as described by Install PHP-FPM on Debian.
• php-tools, command-line tool easing PHP configuration.

This howto recommends:

• biapy-updater, for automatic software updates.

This howto recommends one of this tools:

• the Calibre e-book library manager as described by Install Calibre on Ubuntu.
• a local copy of Calibre library, for example synchronized by using:
  • Seafile, as described by Install Seafile client on Debian.
  • Dropbox.

Settings

Set the domain name hosting the application:

domain='opds.domain.com'

Set the username used to restrict the access to the software by a login (optional):

userName="user"

Set the method used to setup a HTTPS connnection: “auto” to automatically create a free “Let’s Encrypt (en)” SSL certificate, or the name of a SSL certificate created as described by Create a SSL / TLS certificate on Debian (optional, recommended):

sslKeyName="auto"

Provide the path to the Calibre library (synchronized by Dropbox, Seafile, or WebDAV, for example):

calibrePath="/var/lib/cops/${domain}/Calibre"

Set the web site time zone (see List of Supported Timezones on PHP.net (en)):

timeZone="$(command cat '/etc/timezone')"

Additional settings

Set the library’s owner’s name:

authorName="Firstname Lastname"

Set the library’s owner’s web site URL:

authorUrl="http://${domain}/"

Set the library’s owner’s email address:

authorEmail="email@domain.com"

Installation

Detect if sudo is available (“command” is used if not):

cmdProxy='command'
command type -f 'sudo' &>'/dev/null' && cmdProxy='sudo'

Set the software code (used to set the installation paths):

softwareCode='cops'

Set the installation path:

installPath="/opt/${softwareCode}/${domain}"

Clean-up the Calibre library path (removal of the trailing ‘/’):

calibrePath="$(echo "${calibrePath}" | sed -e 's|/$||g')"

Detect if HTTPS is used:

protocol="http"
[[ -n "${sslKeyName}" \
    && ( -e "/etc/ssl/private/${sslKeyName}.key" \
    || "${sslKeyName}" = 'auto' ) ]] && protocol="https"

Create the install path parent folder:

${cmdProxy} mkdir --parent "$(command dirname "${installPath}")"

Environment setup

Install the required software:

${cmdProxy} apt-get install php-gd php-sqlite3 php-json \
    php-intl php-xml php-mbstring php-zip git apg \
    libapache2-mod-xsendfile unzip

Enable xsendfile, expires and rewrite modules for Apache 2:

${cmdProxy} a2enmod xsendfile expires rewrite

Reload PHP and Apache 2 configuration:

${cmdProxy} php-tools --reload
${cmdProxy} systemctl force-reload 'apache2'

Application’s installation

Download the software’s latest stable version:

source="$(${cmdProxy} biapy-downloader \
    --output-path="${installPath}" --extract --forge='github' \
    --file-template='cops-VERSION.zip' 'seblucas/cops')"

Application setup

Create the configuration file:

${cmdProxy} cp "${installPath}/config_local.php.example" "${installPath}/config_local.php"

Set the Calibre library path:

${cmdProxy} sed -i \
    -e "s|calibre_directory.*|calibre_directory'] = '${calibrePath}/';|" \
  "${installPath}/config_local.php"

Enable URL rewriting:

${cmdProxy} sed -i \
    -e "s|cops_use_url_rewriting.*|cops_use_url_rewriting'] = '1';|" \
  "${installPath}/config_local.php"

Enable the conversion to kepub format (for Kobo readers):

${cmdProxy} tee -a "${installPath}/config_local.php" \
    <<< "    \$config['cops_provide_kepub'] = '1';"

Enable X-SendFile use:

${cmdProxy} tee -a "${installPath}/config_local.php" \
    <<< "    \$config['cops_x_accel_redirect'] = 'X-Sendfile';"
customConf="  <IfModule mod_xsendfile.c>
    XSendFilePath \"${calibrePath}\"
  </IfModule>"

Enable the update of epub files metadata before download:

${cmdProxy} tee -a "${installPath}/config_local.php" \
    <<< "    \$config['cops_update_epub-metadata'] = '1';"

Setup the “Send to Kindle / Email” functionnality:

${cmdProxy} tee -a "${installPath}/config_local.php" \
    <<< "    \$config['cops_update_epub-metadata'] = array(
      'smtp.host' => 'localhost',
      'smtp.username' => '',
      'smtp.password' => '',
      'smtp.secure' => '',
      'smtp.from' => '${authorEmail}'
    );"

Enhance the search results:

${cmdProxy} tee -a "${installPath}/config_local.php" \
    <<< "    \$config['cops_normalized_search'] = '1';"

Set the OPDS library owner information:

${cmdProxy} tee -a "${installPath}/config_local.php" \
    <<< "    \$config['cops_author_name'] = '${authorName}';
    \$config['cops_author_uri'] = '${authorUrl}';
    \$config['cops_author_email'] = '${authorEmail}';
"

Access restriction

Generate a random password:

userPassword="$(command apg -q -a 0 -n 1 -M NCL)"

Create a htpasswd file:

[[ -n "${userName}" ]] \
  && ${cmdProxy} htpasswd -cbm "${installPath}/.htpasswd" \
                          "${userName}" "${userPassword}"

Build the proper Apache configuration:

if [[ -n "${userName}" ]]; then
  customConf="${customConf}
  <FilesMatch \"\\.php\$\">
    AuthUserFile \"${installPath}/.htpasswd\"
    AuthName \"${domain}\"
    AuthType Basic
    Require valid-user
  </FilesMatch>"
fi

This configuration (stored in the “authConf” variable) will be aded by a2tools to the application VirtualHost configuration.

Automatic updates

Install the updater script :

${cmdProxy} wget --quiet --no-check-certificate \
    --output-document='/usr/local/bin/cops-updater' \
    'https://raw.githubusercontent.com/biapy/howto.biapy.com/master/updaters/cops-updater'

Declare the downloaded file as executable:

${cmdProxy} chmod +x '/usr/local/bin/cops-updater'

Configure biapy-updater automatic updates to check for newer versions of the updater script:

${cmdProxy} tee -a '/etc/biapy-updater.conf' <<< 'cops-updater'

Setup a cron task for checking daily for newer versions of the software:

${cmdProxy} tee "/etc/cron.d/update-${softwareCode}-${domain//./-}" \
  <<< "#
# Regular cron jobs for updating COPS at ${domain}
#
# Every night at 6 o'clock.
0 6 * * *   root    test -x /usr/local/bin/cops-updater && /usr/local/bin/cops-updater '${domain}'"

Reload cron daemon configuration:

${cmdProxy} systemctl 'restart' 'cron'

VirtualHost setup

Create the HTTP server configuration for the domain:

if [[ -n "${sslKeyName}" \
  && ( -e "/etc/ssl/private/${sslKeyName}.key" \
  || "${sslKeyName}" = 'auto' ) ]]; then
  ${cmdProxy} a2tools --ssl="${sslKeyName}" \
    --custom-options="${customConf}" --overrides='All' \
    "${domain}" "${installPath}"
else
  ${cmdProxy} a2tools  \
    --custom-options="${customConf}" --overrides='All' \
    "${domain}" "${installPath}"
fi

The software is now available on the domain.

This command show the application access information:

echo "URL: ${protocol}://${domain}/
OPDS feed: ${protocol}://${domain}/feed.php
Username: ${userName}
Password: ${userPassword}"

Backup

Backup the installation with Backup Manager (see Install Backup Manager on Debian):

${cmdProxy} backup-manager-tools add "${installPath}"

Bibliography

• A Simpler Guide to Calibre.
• EPUB From the Ground Up: A Hands-On Guide to EPUB 2 and EPUB 3.
• EPUB 3 Best Practices: Optimize Your Digital Books.

Thanks

• Thanks to Calibre OPDS PHP Server (COPS) (en) developers.
• Thanks to Calibre (en) developers.