P U B L I S H I N G community experience distilled Koha 3 Library Management System Savitra Sirohi Amit Gupta Chapter No.4 "Koha's Web Installer, Crontab, and Other Server Configurations"
In this package, you will find: A Biography of the authors of the book A preview chapter from the book, Chapter NO.4 "Koha's Web Installer, Crontab, and Other Server Configurations" A synopsis of the book s content Information on where to buy this book About the Authors Savitra Sirohi heads Nucsoft OSS Labs (http://www.osslabs.biz) a Koha services provider. As part of his work, Savitra has lead several Koha implementations and conducts regular Koha workshops in India. Savitra is an Engineer and has an MBA from the Indian Institute of Management. We would like to thank Kyle Hall, Vimal Kumar, and Nicole Engard and other members of the Koha community who took the time to review the chapter drafts. Their perspective and expertise helped improve this book immeasurably.
Many thanks are due to Wilson, Kavita, Srimoyee, Steven, and others at Packt for their expertise and hard work and also their patience with these first time authors. Amit Gupta is the lead Koha specialist at Nucsoft OSS Labs (http://www. osslabs.biz ), a Koha services provider. Amit has played a key role in several Koha implementations, including the one at Delhi Public Library, one of India's biggest Koha projects. Amit has a BSc and a Master's in Computer Applications.
Koha 3 Library Management System Much of what we have written in this book is based on our experiences teaching Koha installation and maintenance of technology and library staff. We hope this book will help you to quickly install and set up a working Koha installation, complete with catalog data migrated from your current library system. The first nine chapters of this book are devoted to these topics. In the rest of the book we cover topics such as troubleshooting, installing software updates, and customizing Koha, which will be of interest to you when you start to use Koha in earnest. You will need some Linux expertise. Most Koha users use Debian. However you should feel free to try the installation on your preferred distribution. In the examples in this book, we have demonstrated Debian and opensuse commands; we think these two are representative of most commonly used Linux distributions. During the installation process, we would encourage you to seek help from the Koha community via the Koha mailing lists. What This Book Covers Chapter 1, Installing the Software Stack In the first chapter our goal will be to install Koha's software stack the Koha application itself, MySQL database server, Apache2 web server, and the various system and Perl packages Koha uses. Chapter 2, Configuring the Apache2 Web Server Next, we will configure Koha's web server Apache2. Apache2 serves Koha pages to users when they access the OPAC or the staff client. Chapter 3, Installing Koha's Zebra Search Engine In the third chapter we will focus on Zebra Koha's powerful catalog search engine. We will learn how to install and test Zebra. Chapter 4, Koha's Web Installer, Crontab, and Other Server Configurations In the fourth chapter, we will learn about executing Koha's web installer, setting up Koha's Crontab, and configuring Koha services to start automatically when the machine reboots. At the end of this chapter, we will be able to launch Koha. Chapter 5, Configuring the Cataloging Module This chapter is the first of three application configuration chapters. In this chapter, we will learn how to configure Koha's Cataloging module, which is used to maintain information about items in the library.
Chapter 6, Configuring the Circulation Module In this chapter, we will learn how to configure Koha's circulation module. This module is used to loan library items to the patrons. Our goal here will be to map the library's circulation policies to rules and preferences in Koha. Chapter 7, Configuring Other System Preferences In this chapter, we will learn how to configure system preferences related to the rest of Koha's modules Patrons, Acquisitions and Serials, and Online Public Access Catalog (OPAC). We will also study preferences related to styling and appearance, messaging, security, and search. Chapter 8, Test Driving Your Koha Installation By now we will be in a position to take our Koha installation for a test drive. We will look to complete a transaction cycle in each of the primary Koha modules Patrons, Cataloging, Circulation, Acquisitions and Serials. We will also test the reports module and catalog search on the OPAC. Chapter 9, Migrating Catalog Data Migrating catalog data from the legacy system is a prerequisite to using Koha for most libraries. In this chapter we will learn how to convert MARC fi les from legacy systems into Koha compatible fi les. We will learn about Koha's MARC record import tools. Chapter 10, Troubleshooting In this chapter, we will learn about ways to troubleshoot Koha problems, we will learn about the community tools and resources and take a closer look at ten specific problems. Chapter 11, Updating Software It is good practice to keep your Koha software updated to benefit from new features and bug fixes, but also to avoid migration problems if your version falls too far behind. In this chapter we learn how to download and install software updates.
Chapter 12, Customizing Koha Software Most serious Koha users will want to customize the software to suit their needs, perhaps to modify the styling or appearance or to tweak a certain page to show additional information. If you have the skills you can even take on more serious work such as adding new features. In this chapter, we learn how to customize Koha code. Chapter 13, Advanced Topics In this final chapter, we will learn about setting up some less widely used but nevertheless important features of Koha custom record matching rules, LDAP authentication, custom OPACs for each library, internationalization, and setting up Koha as a Z39.50 source.
Koha's Web Installer, Crontab, and Other Server Confi gurations In this chapter, 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. We will set up the koha user's crontab to schedule periodic execution of Koha programs such as those that generate overdue notices or calculate fines. We will also set up an XML parser suitable for use with Koha. Finally we will make sure Koha related services start automatically when the machine reboots. Executing Koha's web installer In this section of the chapter, 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.
Koha's Web Installer, Crontab, and Other Server Configurations 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: [ 52 ]
Chapter 4 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. [ 53 ]
Koha's Web Installer, Crontab, and Other Server Configurations 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. [ 54 ]
Chapter 4 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. [ 55 ]
Koha's Web Installer, Crontab, and Other Server Configurations 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 Z39.50 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 book 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. [ 56 ]
Launching Koha Once the installer finishes it should automatically redirect to the staff interface: Chapter 4 Log in using the MySQL user and you should see Koha's staff interface home page: [ 57 ]
Koha's Web Installer, Crontab, and Other Server Configurations 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. 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 [ 58 ]
Chapter 4 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. [ 59 ]
Koha's Web Installer, Crontab, and Other Server Configurations Rebuilding Zebra indexes In Chapter 3, Installing Koha's Zebra Search Engine, we learned how to rebuild Zebra indexes by passing 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. [ 60 ]
Chapter 4 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 [ 61 ]
Koha's Web Installer, Crontab, and Other Server Configurations 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. 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]. [ 62 ]
Chapter 4 koha@linux:/home/koha/kohaclone/misc # cd /usr/lib/perl5/vendor_perl/5.10.0/xml/sax/ koha@linux:/usr/lib/perl5/vendor_perl/5.10.0/xml/sax # vi ParserDetails. ini [XML::LibXML::SAX::Parser] http://xml.org/sax/features/namespaces = 1 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 book 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 [ 63 ]
Koha's Web Installer, Crontab, and Other Server Configurations 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:~> [ 64 ]
Summary Here is what we learned in this chapter: Chapter 4 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 We have now completed the installation and server configuration phase of the book. In the next set of chapters we will use Koha's staff interface to configure the various Koha modules. In the next chapter, we will configure the cataloging module. [ 65 ]
Where to buy this book You can buy Koha 3 Library Management System from the Packt Publishing website: https://www.packtpub.com/koha-3-library-managementsystem/book. Free shipping to the US, UK, Europe and selected Asian countries. For more information, please read our shipping policy. Alternatively, you can buy the book from Amazon, BN.com, Computer Manuals and most internet book retailers. P U B L I S H I N G community experience distilled www.packtpub.com