Serving the koha-common OPAC with Plack

If you’ve set up a Koha instance and been less than impressed with the responsiveness of the OPAC, this post is for you.

Thanks to the hard work of the Koha Debian package team, it’s easier than ever to get a functional Koha install up and running. But once you’ve set up your new instance, you may find the catalog a little sluggish. If you’ve followed the steps on the Koha Plack wiki page but found they don’t work for the koha-common package, here are a few changes that will set things right.

Before we begin, make sure you are running at least Koha 3.8. Earlier versions are not compatible with Plack, so results may be unpredictable.
Also make sure you have installed all Plack dependencies as listed in the Koha wiki.
Finally, it helps to have already created your Koha instance (with koha-create). Whew!

Except where noted, I put these files in a new /usr/share/koha/misc/plack folder. This guide and these code samples assume you will too.

1. Creating the Koha PSGI wrapper

Create koha.psgi

This file is adapted from the example found on the Koha Plack wiki page. The lib and $root variables have been fixed for koha-common, and a lot of debugging hooks have been removed. The static file paths are correct, but those files should really be served by something leaner like nginx.

Update (1/7/2013): I’ve tweaked this file to allow it to be used for serving the Koha staff site as well, since that is supported with Plack as of 3.10. A more complete guide for that is coming soon, so stay tuned!

#!/usr/bin/perl
use Plack::Builder;
use Plack::App::CGIBin;
use Plack::App::Directory;
 
use lib("/usr/share/koha/lib");
use C4::Context;
use C4::Languages;
use C4::Members;
use C4::Dates;
use C4::Boolean;
use C4::Letters;
use C4::Koha;
use C4::XSLT;
use C4::Branch;
use C4::Category;
 
my $root = ( $ENV{INTRANETDIR} ) ?
                $ENV{INTRANETDIR} . '/cgi-bin' :
                $ENV{OPACDIR} . '/cgi-bin/opac' ;
 
my $app=Plack::App::CGIBin->new(root => $root);
 
builder {
 
        mount "/opac-tmpl"     => Plack::App::File->new(root => "/usr/share/koha/opac/htdocs/opac-tmpl");
        mount "/intranet-tmpl" => Plack::App::File->new(root => "/usr/share/koha/intranet/htdocs/intranet-tmpl");
        mount "/cgi-bin/koha" => $app;
 
};

As the docs say, at this point you can test the OPAC with plackup. Just replace [YOUR INSTANCE NAME] with your instance name in the following and give it a shot.

echo "OPACDIR=/usr/share/koha/opac/ \
	KOHA_CONF=/etc/koha/sites/SITE/koha-conf.xml \
	sudo -u SITE-koha -E plackup --reload /usr/share/koha/misc/plack/koha.psgi" | \
	sed s/SITE/[YOUR INSTANCE NAME]/g | sh

Open your web browser of choice and visit http://[YOUR SERVER IP]:5000/cgi-bin/koha/opac-main.pl.

Congratulations! You have a working OPAC running over twice as fast as it was just moments ago.

For production use, you’ll want to set up a more stable application server. The rest of this article will guide you through making your new OPAC a permanent part of your Koha install by setting up a Starman server and running it through koha-common’s control systems.

To continue, press Ctrl + C to break out of plackup.

2. Serving the OPAC with Starman

Create opac-plack.sh

This was adapted from the opac-plack.sh example posted on the patches mailing list. Create it in your /usr/share/koha/misc/plack directory.

#!/bin/sh -xe
 
test ! -z "$1" && site=$1 && shift
dir=`dirname $0`
 
export KOHA_CONF=/etc/koha/sites/$site/koha-conf.xml
export OPACDIR="$( xmlstarlet sel -t -v 'yazgfs/config/opacdir' $KOHA_CONF | sed 's,/cgi-bin/opac,,' )"
export LOGDIR="$( xmlstarlet sel -t -v 'yazgfs/config/logdir' $KOHA_CONF )"
 
export MEMCACHED_SERVERS=localhost:11211
export MEMCACHED_NAMESPACE=$site
 
PIDFILE=/var/run/koha/$site/plack.pid
 
# Use one of these lines to choose between TCP port and UNIX socket listeners
#SOCKET=/var/run/koha/$site/plack.sock
PORT=5000
 
opt="$opt --access-log $LOGDIR/opac-access.log --error-log $LOGDIR/opac-error.log"
opt="$opt -M FindBin --max-requests 50 --workers 2 -E deployment"
if [ $SOCKET ]; then
    opt="$opt --listen $SOCKET -D --pid $PIDFILE"
elif [ $PORT ]; then
    opt="$opt --port $PORT -D --pid $PIDFILE"
fi
/usr/local/bin/starman $opt $dir/koha.psgi

Make the script executable with: chmod +x opac-plack.sh

Also be sure to make note of the port (or socket file path) in this file, since that’s how you’ll access the OPAC.

You may have noticed that the opac-plack.sh file takes an argument not present in the original. That’s because we’re going to control it with koha-common’s startup infrastructure.

3. Controlling the OPAC server

First we need to create startup and shutdown scripts for Plack.

Create /usr/sbin/koha-start-plack

#!/bin/sh
#
# koha-start-plack -- Start Plack processes for named Koha instances
#
 
set -e
 
for name in "$@"
do
    echo "Starting Plack server for $name"
    exec start-stop-daemon \
        --start \
        --chuid $name-koha \
        --exec /usr/share/koha/misc/plack/opac-plack.sh -- $name
done

Create /usr/sbin/koha-stop-plack

#!/bin/sh
#
# koha-stop-plack -- Stop Plack processes for named Koha instances
#
 
set -e
 
for name in "$@"
do
    echo "Stopping Plack server for $name"
    exec start-stop-daemon \
        --stop \
        --pidfile /var/run/koha/$name/plack.pid
done
echo "Servers stopped"

Be sure to make these scripts executable when you’re finished!

4. Preparing for lanch

Now we update the koha-common init script to start and stop the Plack servers along with the rest of our Koha infrastructure.

Edit /etc/init.d/koha-common

43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

do_start()
{
    # We insure all required directories exist, including disabled ones.
    koha-create-dirs $(koha-list)
    koha-start-zebra $(koha-list --enabled)
+    koha-start-plack $(koha-list --enabled)
}
 
#
# Function that stops the daemon/service
#
do_stop()
{
    # We stop everything, including disabled ones.
    koha-stop-zebra $(koha-list) || true
+    koha-stop-plack $(koha-list) || true
}

Restart koha-common

Now you are ready to put your OPAC into service. Restart your koha-common services with:

service koha-common stop
service koha-common start

That’s it! Your Plack OPAC will now start with your server each time it is restarted, or each time you start and stop the koha-common services. You can also use the koha-[start|stop]-plack scripts to control your OPAC manually, if needed.

Drop me a line in the comments if you have questions or suggestions, or if this article has helped you get the most from your Koha install!