diff --git a/roles/calibre-web/README.rst b/roles/calibre-web/README.rst index b2527156a..2531d146b 100644 --- a/roles/calibre-web/README.rst +++ b/roles/calibre-web/README.rst @@ -1,3 +1,14 @@ +.. |ss| raw:: html + + + +.. |se| raw:: html + + + +.. |nbsp| unicode:: 0xA0 + :trim: + ================== Calibre-Web README ================== @@ -8,14 +19,20 @@ adjust e-book metadata, and create custom e-book collections ("bookshelves"): https://github.com/janeczku/calibre-web#about This Ansible role installs Calibre-Web as part of your Internet-in-a-Box (IIAB) -as a possible alternative to Calibre (we'll call it 'calibre-web' from here -down, noting that ``calibreweb_*`` variables do not include the dash, per -Ansible recommendations). +as a possible alternative to Calibre. + +*WARNING: Calibre-Web depends on Calibre's own /usr/bin/ebook-convert program, +so we strongly recommend you also install Calibre during your IIAB +installation!* + +Please note Calibre-Web's Ansible playbook is ``/opt/iiab/iiab/roles/calibre-web`` +whereas its Ansible variables ``calibreweb_*`` do **not** include the dash, +per Ansible recommendations. Using It -------- -After installation, try out calibre-web at http://box/books (or box.lan/books). +After installation, try out Calibre-Web at http://box/books (or box.lan/books). Typically students access it without a password (to read and download books) whereas teachers add books using an administrative account, as follows:: @@ -23,7 +40,7 @@ whereas teachers add books using an administrative account, as follows:: Username: Admin Password: changeme -If the default configuration is not found, the calibre-web server creates a +If the default configuration is not found, the Calibre-Web server creates a new settings file with calibre-web's own default administrative account:: Username: admin @@ -32,7 +49,7 @@ new settings file with calibre-web's own default administrative account:: Backend ------- -You can manage the backend calibre-web server with these systemd commands:: +You can manage the backend Calibre-Web server with these systemd commands:: systemctl enable calibre-web systemctl restart calibre-web @@ -42,7 +59,7 @@ You can manage the backend calibre-web server with these systemd commands:: Configuration ------------- -To configure calibre-web, log in as user 'Admin' then click 'Admin' on top. +To configure Calibre-Web, log in as user 'Admin' then click 'Admin' on top. Check 'Configuration' options near the bottom of the page. Critical settings are stored in:: @@ -61,18 +78,18 @@ Back Up Everything ------------------ Please back up the entire folder ``/library/calibre-web`` before upgrading — -as it contains your calibre-web content **and** settings! +as it contains your Calibre-Web content **and** settings! Upgrading --------- -Reinstalling calibre-web automatically upgrades to the latest version if your +Reinstalling Calibre-Web automatically upgrades to the latest version if your Internet-in-a-Box (IIAB) is online. But first: back up your content **and** settings, as explained above. **Then move your /library/calibre-web/metadata.db out of the way, if you're -sure you want to (re)install bare/minimal metadata, and force all calibre-web +sure you want to (re)install bare/minimal metadata, and force all Calibre-Web settings to the default. Then run**:: cd /opt/iiab/iiab @@ -83,7 +100,7 @@ Or, to reinstall all of IIAB:: cd /opt/iiab/iiab ./iiab-install --reinstall -Or, if you just want to upgrade calibre-web code alone, prior to proceeding +Or, if you just want to upgrade Calibre-Web code alone, prior to proceeding manually:: cd /opt/iiab/calibre-web @@ -92,22 +109,34 @@ manually:: Known Issues ------------ -* Trying to access an empty public bookshelf causes a system error. +* |ss| Trying to access an empty public bookshelf causes a system error. |se| |nbsp| Appears fixed as of 2018-09-12: `janeczku/calibre-web#620 `_ -* As of August 2018, it's sometimes impossible to set the language of an - e-book: `#1040 `_, `janeczku/calibre-web#593 `_ +* |ss| As of August 2018, it's sometimes impossible to set the language of an + e-book: `#1040 `_, `janeczku/calibre-web#593 `_ |se| |nbsp| Appears fixed as of 2018-09-12: `janeczku/calibre-web#620 `_ -* As of August 2018, calibre-web doesn't yet include Calibre's e-book +* |ss| As of August 2018, Calibre-Web doesn't yet include Calibre's e-book conversion functionality (e.g. Calibre 3.27.1 [released 2018-07-06] allows teachers to convert between PDF, EPUB, HTML, TXT etc — to permit reading on a - wider array client devices and client software). + wider array client devices and client software). |se| |nbsp| This new Calibre-Web + feature (which depends on Calibre's ebook-converter program) needs to be manually + configured in IIAB 6.6 as of 2018-09-12: `janeczku/calibre-web#624 `_ + + Specifically, to enable e-book conversion, log in as Admin/changeme (etc) then + click http://box/books -> Admin -> Basic Configuration -> External binaries. Then + change these 2 settings: + + * Change radio button "No converter" to "Use calibre's ebook converter" + * In textfield "Path to convertertool" type in: ``/usr/bin/ebook-convert`` + * Submit + * Verify that "ebook-convert" appears on Calibre-Web's "About" page at http://box/books/stats + * Test it by clicking any e-book -> Edit metadata -> Convert book format * http://192.168.0.x:8083 does not work, as a result of `iptables `_, even when ``services_externally_visible: true``. This is fixable, but perhaps it's not a priority, as URL's like {http://192.168.0.x/books, http://10.8.0.x/books, http://127.0.0.1/books and http://box/books} all work. -* calibre-web does not currently use version numbers, so glitches might +* Calibre-Web does not currently use version numbers, so glitches might occasionally arise, when upstream developers change its master branch without warning. diff --git a/roles/calibre/defaults/main.yml b/roles/calibre/defaults/main.yml index bdf88373f..ac64a8165 100644 --- a/roles/calibre/defaults/main.yml +++ b/roles/calibre/defaults/main.yml @@ -21,9 +21,9 @@ calibre_src_url: "https://raw.githubusercontent.com/kovidgoyal/calibre/master/se calibre_deb_url: http://download.iiab.io/packages # Must contain both packages for the pinned version, formatted as follows: -# calibre_3.30.0+dfsg-1_all (25M, 2018-08-24) -# calibre-bin_3.30.0+dfsg-1_armhf (742K, 2018-08-30) -calibre_deb_pin_version: 3.30.0+dfsg-1 +# calibre_3.31.0+dfsg-1_all.deb (25M, 2018-09-07) +# calibre-bin_3.31.0+dfsg-1_armhf.deb (747K, 2018-09-12) +calibre_deb_pin_version: 3.31.0+dfsg-1 # USE TO TEST debs.yml (RASPBIAN APPROACH!) ON DEBIAN 9.X: (now handled by calibre_via_debs in /opt/iiab/iiab/vars/*) #calibre_debs_on_debian: True diff --git a/scripts/calibre-install-pinned-rpi.sh b/scripts/calibre-install-pinned-rpi.sh index c0dc408a5..d27c8b0a9 100755 --- a/scripts/calibre-install-pinned-rpi.sh +++ b/scripts/calibre-install-pinned-rpi.sh @@ -10,7 +10,7 @@ export DEBIAN_FRONTEND=noninteractive # Prepares to update to latest from raspbian testing echo "deb http://raspbian.raspberrypi.org/raspbian/ testing main" > /etc/apt/sources.list.d/rpi-testing.list apt update -# @jvonau explains that stale .deb's should be avoided as: "apt will pick the highest version to install after churning a bit..." +# WARNING: you MUST remove old .deb's from /opt/iiab/downloads if upgrading Calibre in this way, SEE: http://FAQ.IIAB.IO "Can I upgrade or reinstall server apps?" apt -y install /opt/iiab/downloads/calibre*.deb #sed -i '$ d' /etc/apt/sources.list.d/rpi-testing.list # Removes last line rm /etc/apt/sources.list.d/rpi-testing.list diff --git a/vars/default_vars.yml b/vars/default_vars.yml index ba13fdb15..23a00db1c 100644 --- a/vars/default_vars.yml +++ b/vars/default_vars.yml @@ -411,6 +411,9 @@ calibre_port: 8080 # Change calibre to XYZ add your own mnemonic URL like: http://box/XYZ calibre_web_path: calibre #NEEDS WORK: https://github.com/iiab/iiab/issues/529 +# WARNING: Calibre-Web (below) depends on Calibre's own /usr/bin/ebook-convert +# program, so we recommend you also install Calibre (above!) + # Calibre-Web alternative to Calibre, offers a clean/modern UX calibreweb_install: True calibreweb_enabled: True diff --git a/vars/local_vars_big.yml b/vars/local_vars_big.yml index be4b30e08..a5465d733 100644 --- a/vars/local_vars_big.yml +++ b/vars/local_vars_big.yml @@ -242,6 +242,9 @@ calibre_port: 8080 calibre_web_path: calibre #NEEDS WORK: https://github.com/iiab/iiab/issues/529 # In addition to: http://box/books box/libros box/livres box/livros box/liv +# WARNING: Calibre-Web (below) depends on Calibre's own /usr/bin/ebook-convert +# program, so we recommend you also install Calibre (above!) + # Calibre-Web alternative to Calibre, offers a clean/modern UX calibreweb_install: True calibreweb_enabled: True diff --git a/vars/local_vars_medium.yml b/vars/local_vars_medium.yml index 9d220a81e..ff035e97f 100644 --- a/vars/local_vars_medium.yml +++ b/vars/local_vars_medium.yml @@ -242,6 +242,9 @@ calibre_port: 8080 calibre_web_path: calibre #NEEDS WORK: https://github.com/iiab/iiab/issues/529 # In addition to: http://box/books box/libros box/livres box/livros box/liv +# WARNING: Calibre-Web (below) depends on Calibre's own /usr/bin/ebook-convert +# program, so we recommend you also install Calibre (above!) + # Calibre-Web alternative to Calibre, offers a clean/modern UX calibreweb_install: True calibreweb_enabled: True diff --git a/vars/local_vars_min.yml b/vars/local_vars_min.yml index b94d5e0eb..1c6a0294a 100644 --- a/vars/local_vars_min.yml +++ b/vars/local_vars_min.yml @@ -242,6 +242,9 @@ calibre_port: 8080 calibre_web_path: calibre #NEEDS WORK: https://github.com/iiab/iiab/issues/529 # In addition to: http://box/books box/libros box/livres box/livros box/liv +# WARNING: Calibre-Web (below) depends on Calibre's own /usr/bin/ebook-convert +# program, so we recommend you also install Calibre (above!) + # Calibre-Web alternative to Calibre, offers a clean/modern UX calibreweb_install: False calibreweb_enabled: False