GeneralThreat.com » Koha

Serving koha-common with Plack

David — Tue, 16 Apr 2013 01:21:59 +0000

This post builds on my last Koha post about running the OPAC on Plack and will modify some of the files from that post. If you haven’t read it, it is a good background post but the snippets are no longer up-to-date.

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.

Hey! Do you want the speed of Plack but don’t want to deal with all of these files? Check out Plackify koha-common on github! This post will eventually go out of date, but the github project will always have the latest scripts and a painless installer.

Let’s begin!

1. Create the PSGI application file

`koha.psgi:`

This is the file that will do the heavy lifting for your Koha install. It is used to run both Intranet and OPAC front-end sites.

#!/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;
 
};

2. Create startup scripts for both the intranet and OPAC

These scripts will handle starting your Plack OPAC and Intranet (respectively) in a way that can be controlled by `koha-common` style start and stop commands.

Note: These scripts assume that you installed Starman from CPAN. If you used your distro’s package manager, you should check your starman path and update these scripts if needed.

`opac-plack.sh:`

Make sure this script is executable!

#!/bin/sh
# --max-requests = decreased from 1000 to 50 to keep memory usage sane
# --workers = number of cores on machine
 
test ! -z "$1" &amp;&amp; site=$1 &amp;&amp; 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/opac-plack.pid
 
SOCKET=/var/run/koha/$site/opac-plack.sock
#PORT=5000
 
# uncomment to enable logging
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

`intranet-plack.sh:`

Make sure this script is executable!

#!/bin/sh
# --max-requests = decreased from 1000 to 50 to keep memory usage sane
# --workers = number of cores on machine
 
test ! -z "$1" &amp;&amp; site=$1 &amp;&amp; shift
dir=`dirname $0`
 
export KOHA_CONF=/etc/koha/sites/$site/koha-conf.xml
export INTRANETDIR="$( xmlstarlet sel -t -v 'yazgfs/config/intranetdir' $KOHA_CONF | sed 's,/cgi-bin,,' )"
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/intranet-plack.pid
 
SOCKET=/var/run/koha/$site/intranet-plack.sock
#PORT=5000
 
# uncomment to enable logging
opt="$opt --access-log $LOGDIR/intranet-access.log --error-log $LOGDIR/intranet-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

2a. Scripts for opening access to socket files

Note: If you’re using sockets instead of TCP ports on Linux, you’ll need to make sure they are world-writable. The following two scripts can be run by koha-start-plack to make sure the sockets are available to any application.

`unlock-opac-plack.sh:`

Make sure this script is executable!

#!/bin/sh
 
test ! -z "$1" &amp;&amp; site=$1 &amp;&amp; shift
 
timeout=0
 
echo "Waiting for OPAC Plack socket for $site"
while [ ! -S /var/run/koha/$site/opac-plack.sock ] &amp;&amp; [ $timeout -lt 10 ]
do
        sleep 1
        timeout=$(($timeout + 1))
done
 
chmod 777 /var/run/koha/$site/opac-plack.sock
echo "OPAC Plack socket open for $site"

`unlock-intranet-plack.sh:`

Make sure this script is executable!

#!/bin/sh
 
test ! -z "$1" &amp;&amp; site=$1 &amp;&amp; shift
 
timeout=0
 
echo "Waiting for Intranet Plack socket for $site"
while [ ! -S /var/run/koha/$site/intranet-plack.sock ] &amp;&amp; [ $timeout -lt 10 ]
do
        sleep 1
        timeout=$(($timeout + 1))
done
 
chmod 777 /var/run/koha/$site/intranet-plack.sock
echo "Intranet Plack socket open for $site"

3. Create control scripts for startup and shutdown

Finally, create the koha-common style start and stop scripts to control your Plack processes.

`/usr/sbin/koha-start-plack:`

This script will start Plack processes for both the Intranet and the OPAC. Like other koha-common scripts, it takes the name of the instance as a parameter. Make sure it’s executable!

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

`/usr/sbin/koha-stop-plack:`

This script will stop Plack processes for both the Intranet and the OPAC. It also takes the name of the instance as a parameter. Make sure it’s executable!

#!/bin/sh
#
# koha-stop-plack -- Stop plack processes for named Koha instances
 
stopopac() {
   local name="$1"
   exec start-stop-daemon \
        --stop \
        --quiet \
        --pidfile /var/run/koha/$name/opac-plack.pid
}
 
stopstaff() {
   local name="$1"
   exec start-stop-daemon \
        --stop \
        --quiet \
        --pidfile /var/run/koha/$name/intranet-plack.pid
}
 
for name in "$@"
do
echo "Stopping Plack servers for $name"
    stopopac "$name" | stopstaff "$name"
 
done
echo "Servers stopped"

4. Prepare Koha to launch Plack

`/etc/init.d/koha-common:`

There are two final changes needed to make Plack a first class part of your koha-common install. Both are made to your /etc/init.d/koha-common file, but they’re both really simple.

First, add the new koha-start-plack script to the do_start() function, just after the koha-start-zebra line.

     koha-start-plack $(koha-list --enabled)

Then add the new koha-stop-plack script to the do_stop() function, just after the koha-stop-zebra line.

    koha-stop-plack $(koha-list) || true

That’s it! Stop and start your koha-common service to enjoy your new Plack infrastructure.

Problems? — Check:

log directory is writable by your *-koha user
tmp directory for compiled templates is writable by your *-koha user

Serving the koha-common OPAC with Plack

David — Tue, 25 Sep 2012 18:58:06 +0000

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`

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!

GeneralThreat.com » Koha

Serving koha-common with Plack

1. Create the PSGI application file

koha.psgi:

2. Create startup scripts for both the intranet and OPAC

opac-plack.sh:

intranet-plack.sh:

2a. Scripts for opening access to socket files

unlock-opac-plack.sh:

unlock-intranet-plack.sh:

3. Create control scripts for startup and shutdown

/usr/sbin/koha-start-plack:

/usr/sbin/koha-stop-plack:

4. Prepare Koha to launch Plack

/etc/init.d/koha-common:

Problems? — Check:

Serving the koha-common OPAC with Plack

1. Creating the Koha PSGI wrapper

Create koha.psgi

2. Serving the OPAC with Starman

Create opac-plack.sh

3. Controlling the OPAC server

Create /usr/sbin/koha-start-plack

Create /usr/sbin/koha-stop-plack

4. Preparing for lanch

Edit /etc/init.d/koha-common

Restart koha-common

`koha.psgi:`

`opac-plack.sh:`

`intranet-plack.sh:`

`unlock-opac-plack.sh:`

`unlock-intranet-plack.sh:`

`/usr/sbin/koha-start-plack:`

`/usr/sbin/koha-stop-plack:`

`/etc/init.d/koha-common:`

Create `koha.psgi`

Create `opac-plack.sh`

Create `/usr/sbin/koha-start-plack`

Create `/usr/sbin/koha-stop-plack`

Edit `/etc/init.d/koha-common`