April 15, 2018

Using the Coce book cover cache with Koha

Earlier I described how I installed the Koha library software system on Debian 8. Koha can display book cover images in search results by fetching the images from Amazon, if you enable the OPACAmazonCoverImages preference in Koha. But Koha needs to query Amazon to get the URL for the images. Furthermore, clicking on the image sends the user to the Amazon site for the book in question. I believe this behavior is required by Amazon’s terms of service, and I consider it incompatible with the goals of a public library. To avoid the use of Amazon entirely, and to speed up the queries for image locations, I installed Coce, a cover image URL caching server.

Log in as root to your Koha server. Fetch the coce code:

git clone

Change to the coce directory and create a config file:

cp config.json.sample config.json

Edit the resulting config.json file. Remove “aws” from the “providers” line, and remove the entire “aws” block. You may also need to change the first “port” value to something other than 8080 to avoid conflicts with other services; some Koha installations use 8080 as staff client port.

Edit coce.js. Remove the statement starting with “var awsProdAdv”, and remove the entire “” function.

Edit package.json and remove the “aws-lib” line.

(I have made my own coce repository that has these changes.)

Now it’s necessary to install redis (key/value database) and nodejs (Javascript server). The method differs depending on whether you’re using Debian 8 or Debian 9.

On Debian 8, install the following packages:

apt-get install redis-server nodejs node-redis node-express

On Debian 9, it’s not quite so simple, because npm (the node package manager) and node-redis (the node interface to redis) are no longer in the standard repositories. Run these commands instead:

apt-get install curl
curl -sL | sudo -E bash -
apt-get install -y nodejs
npm install express --save
apt-get install redis-server redis-tools
npm install redis --save

Start the Coce server:

nodejs app.js

Configure Koha in the staff client by visiting More / Administration / System Preferences / Enhanced Content. Change the “Coce” preference to “Enable”. Change the CoceHost preference to “”, replacing “” with your Koha server’s hostname or IP address (you may need to change 8080 if you changed it earlier in config.json). Change “CoceProviders” to Google Books and Open Library. Hit the Save button.

Test Coce in the OPAC by searching for some books. Some (most?) of the results should show cover images, especially if the books are fairly recent.

To make the Coce server start automatically like other services, create the file /etc/init.d/coce with the following contents:

#! /bin/sh
# Provides:          coce
# Required-Start:    $syslog $time $remote_fs
# Required-Stop:     $syslog $time $remote_fs
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Coce
# Description:       Coce book image cover cache
# Author:       Mark Alexander <>

# set -x


. /lib/lsb/init-functions

case "$1" in
    log_daemon_msg "Starting Coce"
    if pgrep -f "nodejs app.js" ; then
        log_end_msg 1
        chdir /root/coce
        nodejs app.js &
        log_end_msg $?
    log_daemon_msg "Stopping Coce"
    pkill -f "nodejs app.js"
    log_end_msg $?
    $0 stop
    $0 start
    pgrep -f "nodejs app.js"
    echo "Usage: /etc/init.d/coce {start|stop|restart|force-reload|status}"
    exit 1

exit 0

(Note: the method I used above to stop the Coce server, using pkill, may be dangerous if there are other processes on your system that were started with an identical command line.)

Make sure that the init file is executable:

chmod +x /etc/init.d/coce

Then run this command to set up the Coce service so that systemd knows about it:

update-rc.d coce defaults

Now you should be able to start the service using:

systemctl start coce

Stop the service using:

systemctl stop coce

Check the status of the service using:

systemctl status coce

Update: After using coce for a few months in a live installation, I found that it occasionally crashes, apparently due to some malformed html that it receives from I am not skilled enough in Javascript to know how to fix this problem, so I used a kludge to work around the problem: I arranged for coce to be restarted once a day. As root, I used crontab -e to add the following line to the root’s crontab:

0 5  *   *   *     /etc/init.d/coce restart

Update 2: Today the DNS servers for our Koha host went offline, causing coce to store empty strings in its Redis cache for book cover URLs. This meant that when the DNS problems went away, the affected book cover images still didn’t show in the Koha OPAC. The fix was to clear the Redis cache using this command:

redis-cli flushdb

Update 3: A better way than a cron job to restart coce after it crashes is to arrange for systemd to do the job. I did this by first creating the directory /etc/systemd/system/coce.service.d . Then I created the file restart.conf in that directory, with the following contents:


Finally, I ran the command systemd daemon-reload, which told systemd to read the new configuration.