Koha's Web Installer, Crontab, and Other Server Configurations

Exclusive offer: get 50% off this eBook here
Koha 3 Library Management System

Koha 3 Library Management System — Save 50%

Install, configure, and maintain your Koha installation with this easy-to-follow guide

$26.99    $13.50
by Amit Gupta Savitra Sirohi | November 2010 | Open Source

In this article, by Amit Gupta & Savitra Sirohi, authors of Koha 3 Library Management System, we will complete Koha's installation and system configuration tasks. First we will execute Koha's web installer to populate the Koha database structure and some important administrative settings. This will allow us to launch Koha's staff interface and its OPAC.

This article specifically covers:

  • Executing Koha's web installer
  • Configuring the crontab
  • Ensuring Koha starts automatically on server reboot
  • Configuring the correct SAX parser
  • Setting up environment variables for the Linux shell

 

Koha 3 Library Management System

Koha 3 Library Management System

Install, configure, and maintain your Koha installation with this easy-to-follow guide

  • A self-sufficient guide to installing and configuring Koha
  • Take control of your libraries with Koha library management system
  • Get a clear understanding of software maintenance, customization, and other advanced topics such as LDAP and Internationalization
  • Written in a style that applies to all Linux flavors and Koha versions

 

        Read more about this book      

(For more resources on this subject, see here.)

Executing Koha's web installer

In this section of the article, we will learn how to execute Koha's web installer. The web installer performs several important functions such as creating Koha's database structure or populating mandatory administrative settings. It can also populate optional settings and sample data such as MARC frameworks or patron categories. The installer is launched from the staff client interface using Koha's MySQL user and is a series of interactive steps. At the end of the process we will be able to launch Koha's staff interface and its OPAC.

Understanding the web installer's functions

Koha's web installer performs the following functions:

  • Checks for the existence of Koha's database, the connectivity to the database, and if the database user has the required privilege on the Koha database.
  • Creates Koha's database structure—its tables, relationships between tables, database constraints, and other rules.
  • Accepts user input on important configuration questions such as Language or MARC flavor.
  • Populates the Koha database with several mandatory administrative settings such as the default system preferences.
  • Populates the Koha database with several optional administrative settings and sample data such as MARC bibliographic frameworks, sample libraries, or sample patron categories.
  • Configures Koha catalog search to use Zebra or to use database indexing.

Understanding how to execute the web installer

Here are some important points to note about executing Koha's web installer:

  • The web installer is launched from the staff interface.
  • We use a MySQL database user and password to login into the installer; this user must have privileges over Koha's database.
  • Choosing the correct MARC flavor—MARC21 or UNIMARC is very important; it is not possible to change this configuration once the database is created.
  • If you are evaluating or testing Koha, you should choose to import most or all of the optional settings and sample data. This way you can start using Koha right away.
  • The optional settings and sample data can be deleted or edited from Koha's staff client at any time, but this can be significant amount of work.
  • If you have made a mistake in the configuration settings and want to start over, simply drop and recreate Koha's database from the MySQL prompt; you will be able to launch the web installer once again.

Understanding optional data available for import

Let us understand some of the optional setting and sample data that we can choose to install using the web installer.

Settings for MARC frameworks

MARC frameworks define how data is captured for different types of material. The frameworks control things such as, which MARC fields are used, which of these fields is mandatory, or which fields are under authority control.

The installer has three sets of optional settings that we can import:

  • Matching rules: Matching rules are used during import of catalog records to match incoming records to those already in the database. Further action can be taken on matched records such as overwriting old records or adding holdings records. Two matching rules are available: one matches on ISBN and other on ISSN.
  • Fast Add framework: This framework is designed for quickly adding catalog records; it has fewer fields when compared to other frameworks.
  • Simple MARC 21 Bibliographic frameworks: A set of bibliographic frameworks for common types of material such as books, CDs, or serials.

Other data

Here is a listing of data we can import under the Other data section:

  • Authorized values: Authorized values are lists of values that control data entry into catalog fields. Here we can import lists along with sample values for fields such as collections, shelving locations, or item statuses.
  • Currencies: A set of currencies with sample exchange rates for use in Koha's Acquisitions module.
  • Sample patron types and categories: A set of sample patron categories such as Student, Teacher, or Staff. Patron categories are used to define rules such as membership duration; the categories are also used to define circulation policy such as loan period.
  • Sample Label and Patron Card Data: A set of sample layouts and templates for use in Koha's label and patron card generation, and printing tool.
  • Sample Holidays: A sample set of holidays for use in Koha's calendar. The calendar is used in Koha's circulation module to calculate due dates and fines.
  • Default Item Types: A sample set of item types. Item types are used to define circulation policy such as loan period or fine amount.
  • Sample Libraries: A sample set of libraries, patrons, catalog items, circulation rules are linked to libraries.
  • Sample News Items: A set of sample news items, for display on the OPAC and the staff interface.
  • Default messages or notices: A set of sample notices. These are used in various Koha modules, for instance the Overdue notice can be configured to be sent to patrons with overdue items.
  • Sample Patrons: A set of patron records.
  • Sample Z3950 servers: A sample set of Z39.50 servers such as that of the Library of Congress. These servers are used in Koha's cataloging module for copy catalog records into Koha.

Executing the web installer

Here are step-by-step instructions on executing the web installer:

  1. Log in using the MySQL user and password; in this article we have used the user kohaadmin.
  2. In Step 1, choose your language; you should see just one option here—en for English or fr for French.
  3. In Step 2, the installer checks the database connectivity and user privileges.
  4. In Step 3, the installer populates the database with tables before prompting the user to install basic configuration settings.
  5. Select your MARC flavor—Unimarc or MARC 21. It is important to make the right choice here. Consult with your library staff if you are unsure of what to choose.
  6. Choose to import optional data related to MARC frameworks.
  7. Choose to import other optional data such as authorized values, currencies, or patron categories.
  8. Click on Import to install the settings and sample data.
  9. Choose to use Zebra or the regular database indexing.
  10. Click on Finish to complete the execution of the web installer.

Launching Koha

Once the installer finishes it should automatically redirect to the staff interface:

Log in using the MySQL user and you should see Koha's staff interface home page:

To launch the OPAC navigate to the OPAC url and you should see a screen such as this:

Configuring the crontab

Several Koha programs need to be run periodically. These programs calculate fines, generate overdue notices, send out e-mails, or build Zebra indexes.

We use Linux's Cron utility to schedule the execution of these programs.

Koha 3 Library Management System Install, configure, and maintain your Koha installation with this easy-to-follow guide
Published: November 2010
eBook Price: $26.99
Book Price: $44.99
See more
Select your format and quantity:
        Read more about this book      

(For more resources on this subject, see here.)

Editing the crontab

The cronjobs are set up under the koha user's crontab. To edit the crontab we run the command crontab with the –e option:

koha@koha@linux:~> crontab -e

To save and exit, we use the vi command wq:

:wq

Setting up environment variables

The first thing we need to do is to set Koha related environment variables in the crontab; without these none of the cronjobs will execute. Add these lines in the crontab, somewhere at the top:

PERL5LIB=/home/koha/kohaclone
KOHA_CONF=/etc/koha-dev/etc/koha-conf.xml

Generating advance notices

Advance notices are sent to patrons when items are due. To generate such notices, we need to script advanced_notices.pl as a cronjob. Add a line to the crontab as follows:

49 5 * * * perl /home/koha/kohacone/bin/cronjobs/advance_notices.pl -c

This cronjob will execute at 5:49 AM every day and generate and queue advance notices messages to patrons.

Generating overdue notices

Overdue notices are sent to patrons when items are past due. To generate such notices, we need to script overdue_notices.pl as a cronjob. Add a line to the crontab as follows:

45 5 * * * perl /home/koha/kohaclone/bin/cronjobs/overdue_notices.pl -t

This cronjob will execute at 5:45 AM every day and generate and queue overdue notices messages to patrons.

Sending e-mail messages

To send e-mails to patrons we will need to script process_messages.pl in the crontab:

30 6 * * * perl /home/koha/kohaclone/bin/cronjobs/process_message_queue.
pl

The process_messages.pl program sends out the queued messages via e-mail. This is the reason it should be scheduled after the advance notices and overdue notices cronjobs. In this example, we have scheduled the program to run at 6:30 AM every day.

Calculating fines

To calculate fines we script fines.pl as follows:

0 7 * * * perl /home/koha/kohaclone/bin/cronjobs/fines.pl

The fines.pl program calculates fines on overdue items based on circulation rules setup in Koha.

Rebuilding Zebra indexes

to rebuild Zebra indexes pass different parameters to the rebuild_zebra.pl program. To schedule index rebuilds, we script a cronjob as follows:

*/1 * * * * perl /home/koha/kohaclone/misc/migration_tools/rebuild_
zebra.pl -b -a -z >> /dev/null 2>&1

Note the following about this cronjob:

  • The */1 at the beginning the cronjob signifies that the command will be executed every minute
  • The output of the command is being redirected to the /dev/null, which means nowhere
  • The expression 2>&1 means, that the command's error messages (2) and its standard output (1) will both be redirected to the same place, in this case /dev/null

To redirect the output and error messages to a log file, we setup the cronjob as follows:

*/1 * * * * perl /home/koha/kohaclone/misc/migration_tools/rebuild_
zebra.pl -b -a -z >> /home/koha/logs/zebra.log 2>&1

Note the use of the file /home/koha/logs/zebra.log instead of /dev/null.

More crontab examples

There are several other programs that can be set up in the crontab depending on your requirements. Take a look at the /misc/cronjobs/crontab.example file for more information:

koha@koha@linux:~> vi /home/koha/kohaclone/misc/cronjobs/crontab.example

Ensuring Koha starts automatically on server reboot

To make sure that Koha runs smoothly after a server reboot, we need to make sure that Apache2, MySQL, and Zebra server start up automatically. In this section, we demonstrate how to set this on Debian and openSuSE.

Auto-starting Apache2

On Debian, Apache2 is configured by default to start automatically on server reboot. In openSuSE, however, this is not the case. We use the chkconfig program to configure Apache2 to auto-start on reboot:

koha@koha@linux:~> sudo chkconfig apache2 on

Let us test if the command was successful; we run the command as follows:

koha@koha@linux:~> sudo chkconfig apache2
apache2 on

Auto-starting MySQL

Again on Debian, MySQL is already configured to start automatically on server reboot. In openSuSE, we use chkconfig to configure it to auto-start on reboot:

koha@koha@linux:~> sudo chkconfig mysql on

To test the configuration, we use chkconfig as follows:

koha@koha@linux:~> sudo chkconfig mysql
mysql on

Auto-starting Zebra server

We need to configure the service koha-zebra-daemon to start up automatically on server reboot.

On Debian, we use the chkconfig equivalent command—update-rc.d to accomplish this:

koha@koha@linux:~> sudo update-rc.d koha-zebra-daemon defaults

On openSuSE, we use chkconfig as follows:

koha@koha@linux:~> sudo chkconfig koha-zebra-daemon on

On openSuSE, if you are not using the koha-zebra-daemon service, you can setup the zebrasrv command in the /etc/init.d/boot.local file.

Edit the boot.local file:

koha@koha@linux:~> sudo vi /etc/init.d/boot.local

Add the zebrasrv command to the file somewhere near the end of the file as follows:

# script with local commands to be executed from init on system startup
#
# Here you should add things, that should happen directly after booting
# before we're going to the first run level.
#
/usr/bin/zebrasrv -f /etc/koha-dev/etc/koha-conf.xml &

Note the use of the & character at the end of the zebrasrv command; this tells the command to run silently in the background.

Koha 3 Library Management System Install, configure, and maintain your Koha installation with this easy-to-follow guide
Published: November 2010
eBook Price: $26.99
Book Price: $44.99
See more
Select your format and quantity:
        Read more about this book      

(For more resources on this subject, see here.)

Configuring the correct SAX parser

Koha uses Simple API for XML (SAX) parsers to process XML data. It is possible that multiple XML parsers are installed on the server. We need to use the LibXML::SAX::Parser. The other parsers such as XML::SAX::PurePerl or XML::SAX::Expat are known to have bugs with certain character types.

First we run a test to check which parser is setup on the server. To print the parser that is in use, we run the Koha program /misc/sax_parser_print.pl:

koha@koha@linux:~> cd /home/koha/kohaclone/misc/
koha@linux:/home/koha/kohaclone/misc # ./sax_parser_print.pl
Koha wants something like:
XML::LibXML::SAX::Parser=HASH(0x81fe220)
You have:
XML::LibXML::SAX=HASH(0x834fea4)
Looks bad, check INSTALL.* documentation.

That error, looks bad, indicates that the configured parser is not suitable for Koha use. We will need to edit the initialization file of the parser and change its configuration.

First we locate the file ParserDetails.ini:

koha@linux:/home/koha/kohaclone/misc # locate ParserDetails.ini
/usr/lib/perl5/vendor_perl/5.10.0/XML/SAX/ParserDetails.ini

We edit this file replace [XML::SAX::PurePerl] or [XML::SAX::Expat] as the case may be with [XML::LibXML::SAX::Parser].

koha@linux:/home/koha/kohaclone/misc # cd
/usr/lib/perl5/vendor_perl/5.10.0/XML/SAX/

Let us test the parser configuration again; a correct file will result in an output like this:

koha@linux:/home/koha/kohaclone/misc # ./sax_parser_print.pl
Koha wants something like:
XML::LibXML::SAX::Parser=HASH(0x81fe220)
You have:
XML::LibXML::SAX::Parser=HASH(0x834fc94)
Looks good.

Setting up environment variables for the Linux shell

To run any of the Koha's programs from the Linux shell we need to set up up two environment variables properly—KOHA_CONF and PERL5LIB. Koha's Perl programs look at these variables to determine the location of the installation's configuration file – koha-conf.xml and the location of the application folder – kohaclone. In this section, we demonstrate how to setup these variables up for a single session and how to set these up to be persistent across sessions.

Setting up KOHA_CONF environment variable

The KOHA_CONF environment variable should point to Koha's configuration directory; in this article we have used /etc/koha-dev/etc/koha-conf.xml. To set up this variable, we use the export command:

koha@linux:/home/koha/kohaclone # export
KOHA_CONF=/etc/koha-dev/etc/koha-conf.xml

Let us test to make sure the variable is set correctly:

koha@libux:/home/koha/kohaclone # echo $KOHA_CONF
/etc/koha-dev/etc/koha-conf.xml

Setting up PERL5LIB environment variable

The PERL5LIB environment variable points to the kohaclone folder. To set up this variable, we use the export command as follows:

koha@linux:/home/koha/kohaclone# export PERL5LIB=/home/koha/kohaclone

Let us test to make sure the variable is set correctly:

koha@linux:/home/koha/kohaclone# echo $PERL5LIB
/home/koha/kohaclone

Setting up persistent environment variables

To make sure the variables are persistent across sessions, we will need to export these variables in a bash configuration file.

On Debian, we set these up in the /etc/bash.bashrc file:

koha@linux:/home/koha # vi /etc/bash.bashrc

On openSuSE, we use the /etc/bash.backrc.local file:

koha@linux:/home/koha # vi /etc/bash.bashrc.local

We add these lines to the file:

export KOHA_CONF=/etc/koha-dev/etc/koha-conf.xml
export PERL5LIB=/usr/share/kohaclone

To test if the configuration is successfully setup, we open a new terminal session and run the echo command:

koha@linux:~> echo $KOHA_CONF
/etc/koha-dev/etc/koha-conf.xml
koha@koha@linux:~> echo $PERL5LIB
/home/koha/kohaclone
koha@linux:~>

Summary

Here is what we learned in this article:

  • Executing Koha's web installer to populate the database structure and mandatory administrative settings
  • Configuring the crontab to schedule Koha's batch programs
  • Configuring the necessary XML SAX parser
  • Configuring Apache2, MySQL, and Zebra server to start automatically on reboot

Further resources on this subject:


About the Author :


Amit Gupta

Amit Gupta works on Koha implementations in Nucsoft OSS Labs. He played a key role in the Delhi Public Library implementation, one of India's biggest Koha projects. Amit has a BSc and a Masters in Computer Applications.

Savitra Sirohi

Savitra Sirohi leads Nucsoft's OSS Labs unit. He has a dozen years of experience in the software industry in development and project management roles. He has been involved with several Koha implementations and conducts Koha installation workshops in India. Savitra is an Engineer and has an MBA from the Indian Institute of management.

Books From Packt


YUI 2.8: Learning the Library
YUI 2.8: Learning the Library

Learning Ext JS 3.2
Learning Ext JS 3.2

Apache MyFaces 1.2 Web Application Development
Apache MyFaces 1.2 Web Application Development

NHibernate 3.0 Cookbook
NHibernate 3.0 Cookbook

Apache CXF Web Service Development
Apache CXF Web Service Development

Moodle 2.0 First Look
Moodle 2.0 First Look

Drupal 7
Drupal 7

jQuery UI 1.7: The User Interface Library for jQuery
jQuery UI 1.7: The User Interface Library for jQuery


Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software