Running Coce book cover caching server in https for Koha 20.05

This post is related to a previous one in which I described my process of moving Koha 20.05’s OPAC over to https. I also mentioned the problem of mixed content in https environments. One service that may cause a mixed content warning in browsers is Coce, a book cover caching server written originally by Frédéric Demians, and later modified by Mark Alexander. That’s because Coce was initially written to run over http only. Thanks to the efforts of Mark Alexander, however, Coce is now adapted to https environments!

In what follows I shall describe the process I took to install Coce. Beforehand, I’ll describe my server set-up, how I originally got Coce to run in http, and then how I got Coce to run in https.

I hope that this post will assist fellow Koha tinkerers in not only improving upon their library’s metadata, but to widen their knowledge in Web application and database maintenance. As in all of my Koha-related writings, I assume no expertise. Although I am a professional librarian, I am an amateur in server, Web, and database administration. Caveat emptor, please!

System information

  • Koha 20.05.00.000
  • Running Plack, Memcache, Zebra
  • Apache 2.4.29
  • MariaDB 10.1.44
  • Ubuntu 18.04 (Bionic)

Installing Coce, or version the first (http)

Best described by Galen Charlton, Coce is a service which caches the URLs of book cover images from several sources (Amazon, Open Library, and Google Books) instead of the images themselves for, among other reasons, better server performance and page loading. The images are then displayed next to each bibliographic record with an ISBN (MARC21 field 020$a) in a Koha library, like so:

An example of a book cover image retrieved from Open Library. Its URL is cached by Coce.

Provided one or more of the book cover sources has an image, something will be displayed. If none of the sources have a cover, nothing will be displayed, and you may have to resort to scanning and uploading a local cover. I try avoiding this because storing image files locally can be a big drain on performance depending on your set-up. Having a server cache URLs instead of images themselves is optimal.

Since ca. 2013, Koha has supported Coce by having it available as a system preference. In order to connect a Koha library to Coce, a Coce server is needed. One can run one locally or connect to one elsewhere. To run one locally, Coce, whose footprint is very small and takes up only a small amount of server resources, requires installation of a Redis server first. Installation instructions for the original version of Coce can be found on Github. Once the Redis server is up and running, you can install, configure, and start Coce.

The following steps require knowledge of using Linux via a command line interface, retrieving software from Github therein, as well as general server maintenance knowledge (UFW, file directory structure in Ubuntu, how to SSH into your server using Putty, etc.). There are many, many resources online that will assist you with these tasks. It’s how I learned!

Basic steps

After logging into your server, do the following:

  1. Create a new directory for Coce:
    • mkdir /usr/local/coce
  2. Grab Coce from Github
    • Navigate to your Coce directory: cd /usr/local/coce
    • Clone Coce to your server: git clone https://github.com/fredericd/coce.git
  3. Install Redis
  4. Install node.js
    • Navigate to your Coce directory: cd /usr/local coce
    • Run the following command: npm install
  5. Configure Coce
    • Rename the config.json.sample file to config.json
    • Define within the config file the port you want Coce to run on. For http, I think the default is set to 8080. This may be a problem since the Koha staff client defaults to 8080. I changed my Coce to run on port 8081 instead.
    • Ensure that providers has gb,aws,ol (i.e., Google Books, Amazon, Open Library) defined
    • Ensure your Redis port is defined correctly. Redis installs on port 6379. Remember: keep whatever port you use for Redis firewalled! Never open it.
  6. Start Coce
    • Ensure that you are in your Coce directory
    • Run: node app.js $
  7. Open the port on which Coce is running:
    • ufw allow from port xxxx, where xxxx is your port number
    • You should then see a white page with a “Welcome to Coce” statement after navigating to your URL. Mine was http://library.craigbutosi.ca:8081 when I was on http.

Keeping Coce Running

One of the trickiest aspects of running Coce is ensuring that it runs and restarts whenever the server reboots. One way, as mentioned on Frédéric’s Github space (is through the use of use of Phusion Passenger and by including the command to run Phusion on the port Coce uses by including it in your rc.local file. This will remind Ubuntu to start after a server reboot. (Note that this method is required if you’re running Coce in http. For https, the process is simpler).

In my instance, I used Phusion Passenger listening on port 8081 (for http) and also added the following line in my /etc/rc.local file:

A snapshot of /etc/rc.local with the command to run Passenger. This reminds the server to start passenger, and, in turn, Coce.

One of the issues you might come across is keeping Coce running after starting it in the command line. After you install Redis, install Coce, configure Coce, I found that after starting Coce like so:

$ node app.js

everything seems fine, until you CTRL + C or CTRL + Z out of the window. What wasn’t mentioned on the Github pages is to ensure that you append a ‘$’ (without quotes) to that command:

node app.js $

This is important to keep it running after you cancel out of your session.

Installing Coce, or version the second (https)

The steps to install Coce over https are identical to the method above. However, rather than cloning Demians’ version, clone Alexander’s version instead. Navigate to your Coce directory, then:

git clone git@gitlab.com:bloovis/coce.git

If you want to replace Demian’s version of Coce on your server already with Alexander’s, all I did was remove the Coce folder in /usr/local/coce, made sure I was in my Coce directory, and repeated steps 2, 5, and 6 above, making sure I selected a different port for https.

When you go into the config file, you’ll notice the default port used for https is 8443, which works fine. I decided to remove the http port line (8081) because I didn’t need an http server running as well. After setting up the restart.conf and coce.init file (see next section), my Coce server is now running over https:

https://library.craigbutosi.ca:8443

Restart.conf and Coce.init

There are two added features in Alexander’s adapted Coce software: an init script and and a restart.conf file which takes the place of the Phusion passenger/rc.local method, ensuring that Coce restarts if the server is ever rebooted.

When you downloaded Alexander’s Coce into your directory, you may have seen the following file:

restart.conf

If you open the file, you see the following instructions:

“Copy this file to the /etc/systemd/system/coce.service.d directory (create the directory first)”:

  • Create the directory: mkdir etc/systemd/system/coce.service.d
  • Copy the file: cp /usr/local/coce/restart.conf /etc/systemd/system/coce.service.d

Voila. No more phusion passenger or rc.local needed.

You may also have seen:

coce.init

This file makes it possible to start, stop, restart, force reload, and check the status of Coce like any other Linux program:

$ service coce status
$ service coce start
$ service coce stop
$ service coce force-reload

More information on this can be found at Alexander’s blog, bloovis.com

Conclusion

Finally, a personal thanks to Demians and Alexander for their time writing and developing this important piece of software for use with Koha! Coce provides an added layer of metadata enrichment to bibliographic records to improve discoverability and to more easily identify and locate items. Because it caches URLs rather than storing image files, retrieval is faster and server resource use is kept to a minimum.

Craig Butosi
Library professional of ten years, with six years of library management and administration experience. Graduate of critical media studies and music. Autodidact and lover all things that inch us closer to the good life.