Koha 3 Library Management System

Chapter 1. Installing the Software Stack

In this chapter, our goal will be to install Koha's software stack—the Koha application itself and the various system and Perl packages it uses. Installing the stack in itself is not enough to be able to use Koha, but is an important first step.

This task can be quite challenging, especially for novice Linux users. You will need to get familiar with using the Linux terminal and multiple installation tools. Expect problems with Perl modules, as troubleshooting these can be especially difficult.

We cover the chapter in three stages—first an orientation, next preparatory steps, and finally a demonstration of the installation. Throughout this book we will use two Linux distributions—Debian and openSuSE; the two combined are representative of most other distributions.

An orientation to Koha's installation

In this section we'll learn about:

What components we will need to install
What installation tools to use and when
The implications of choosing one Linux distribution over another
Where to get help when you run into installation problems

Koha's architecture

First, let us take a quick look at Koha's architecture. Koha runs on the Linux, Apache2, MySQL, Perl (LAMP) platform:

Linux: The operating system
Apache2: The web server
MySQL: The database server
Perl: Koha is written in the Perl programming language

What do we need to install?

We will install various packages related to:

The Koha architecture above—Linux, Apache, MySQL, and Perl
The Koha application itself
Build and compiler programs that help with the installation
Various Perl and non Perl packages that Koha uses, along with their own prerequisites

Installation tools

Let us take a look at the various tools we will use to install Koha's software stack. These tools are:

Package manager: To install Linux packages
Make utility: To install Perl modules
CPAN shell: To install Perl modules that are not available as Linux packages
Git: To download the Koha application

Package manager

A package manager makes installation easy by automatically installing prerequisites, tracking versions and updates, and verifying checksums. Your choice of the package manager will usually depend on the Linux distribution you use. Here are some popular package managers:

APT: On Debian or Ubuntu
YaST: On openSuSE
YUM: On CentOS

Make utility

Perl programs such as Koha or the various Perl modules it uses can be installed using a series of commands:

perl Makefile.PL: This command checks for prerequisites and creates a configuration file needed by make
make: This compiles the software and creates executables
make test: It runs test cases to ensure proper installation, flags errors, and warnings in case of problems
make Install: This installs the executable files into proper directories in the server

CPAN shell

CPAN (Comprehensive Perl Archive Network)—is an archive of Perl modules.

The CPAN shell is a tool that automates the download and installation of Perl modules from the archive including the execution of the perl Makefile.PL, make, make test, and make install commands given above.

Learn more about CPAN here: http://www.cpan.org/.

Git

Git is Koha's version control system. Git simplifies and automates the download of software from Koha's online repository. We use Git not only during installation, but also while installing software updates. If you wish to make software changes of your own, Git will help merge those changes with new versions of Koha.

Learn more about Git here: http://git-scm.com/.

Choosing between Linux Perl packages and CPAN modules

CPAN is the largest archive of Perl modules. Perl modules are always available on CPAN. Many, but not all of Koha's Perl prerequisites are available as packages in a distribution's sources.

The recommended approach in such a scenario is to use Linux packages where available. If you don't find packages for a certain module, then use CPAN to install it.

The Linux package manager can manage all prerequisites of a module. CPAN only knows about Perl prerequisites, and cannot install any non-Perl prerequisites. For this reason, you will likely have smoother installations with the package manager in comparison to CPAN.

Choosing a Linux distribution

It appears that Debian is the most popular when it comes to Koha. Some of the installation tasks are simpler in this distribution. Also you might get better community support from a large pool of Debian Koha users.

However, if you are skilled on another distribution, it might make sense to use that. Installation on Ubuntu is very similar to that on Debian. There are many Koha users on Fedora, CentOS, or openSuSE. Installation documents, live CDs, and other sorts of help are becoming available for these distributions as well.

In any case, once you are past the installation stage, it does not really matter distribution you are on.

Getting help—Koha's community resources

If you face trouble with the installation, Koha's community resources can be of excellent help:

Mailing lists: Koha's mailing lists are very active and you are likely to get timely help. Join the mailing lists via this page: http://koha-community.org/support/koha-mailing-lists/.
Mailing lists archives: Many of the discussions are indexed by search engines. If you run into trouble, it is likely someone else had a similar problem before you, so just search for solutions using your favourite search engine.
IRC chat: Many of Koha's developers are available on this live chat forum. Join here: http://koha-community.org/support/.
Wiki: Koha's wiki might have useful material - http://wiki.koha-community.org/.
Installation documents: Up-to-date installation documents are available in Koha's application folder.

Preparing for installation

In this section we prepare for the installation—setting up a server, preparing a list of packages for installation and configuring installation tools.

Server prerequisites

Before we start the installation, we will need a server setup as follows:

Prerequisites	Description
Server	2 GB RAM, 40 GB hard disk should be good for most libraries.
Internet connection	High speed Internet connection to download software.
Linux	Your preferred distribution installed on the server.
Firewall ports opened	Git port 9418 FTP port 21 HTTP port 80
Access	Access to the server via SSH, or directly.
User	A Linux user with sudo privileges, in this book we use user—koha.
Locale	Your locale setup on the server.

Downloading Koha and switching to a branch

One of the first things we do is to download Koha and switch to a version (or a branch) that we want to use. This helps us draw up, as explained in sections below, our package installation list.

Cloning Koha

To download the Koha application, we need Git. Let us install Git:

koha@li190-245:~$ sudo apt-get install git

Now we are ready to download Koha, let us change to a folder where we want to install Koha. The user koha must own this folder:

koha@li190-245:~ # cd /home/koha

To clone the application from Koha's git server we use the git clone command:

koha@li190-245:~$ git clone git:://git.koha-community.org/koha.git kohaclone

Checking out a branch

Before installing Koha, we need to select the software version or branch that we want to use. In production environments, you may want to use the stable version. In test environments you might want to use the latest version—master.

Let us say we want to install the stable version. A quick check on http://git.koha-community.org tells us that at the time of writing this chapter, the correct name of the stable branch is v3.00.06.

To use Git, we need to be in the kohaclone folder:

koha@ li190-245:/home/koha # cd kohaclone

To switch to this branch, we use the git checkout command:

koha@li190-245:~/kohaclone$ git checkout -b koha-stable v3.00.06

Preparing a list of installation packages

Preparing a list of installation packages can be a challenge depending on which distribution you are on. At the time of writing, package lists are available for Debian and Ubuntu only. We cannot use the same packages on other distributions—some packages may be named differently, and others may not be available at all. Also some packages that Koha requires may be available on your distribution and not on Debian and Ubuntu.

System packages

We use the term system packages for non-Perl modules. Here is a list of system packages that you must have in your installation list; you will need to to look up the right names for each of these from your distribution's sources:

Package	Description
Apache2	The web server.
MySQL	The database server.
Make	Programs that helps build and install packages.
Gcc	Is the compiler package.
Yaz	Is the toolkit used in Z39.50 clients and servers.
Libyaz	YAZ related libraries.
Libyaz-devel	YAZ related development libraries.

On Debian, to look up the name of a package we use the apt-cache search command:

koha@li190-245:~$ sudo apt-cache search libyaz

On openSuSE, we use the search tool available inside the YaST GUI:

koha@li190-245:~$ yast

Perl modules

An accurate list of Perl modules can be drawn up by running Koha's Makefile.PL program. The program checks for the installation status of Koha's Perl module prerequisites and displays warning messages for each missing module.

We run Koha's Makefile.PL program as follows:

koha@li190-245:~/kohaclone$ perl Makefile.PL

See the section on Makefile.PL below to see how to choose various options, or you can choose default value for now. The missing module prerequisites will be displayed at the end:

[Thu Aug  5 05:07:41 2010] Makefile.PL: Warning: prerequisitePDF::Reuse::Barcode 0.05 not found.
[Thu Aug  5 05:07:41 2010] Makefile.PL: Warning: prerequisiteSMS::Send 0.05 not found.
[Thu Aug  5 05:07:41 2010] Makefile.PL: Warning: prerequisiteSchedule::At 1.06 not found.
[Thu Aug  5 05:07:41 2010] Makefile.PL: Warning: prerequisiteText::CSV::Encoded 0.09 not found.
[Thu Aug  5 05:07:41 2010] Makefile.PL: Warning: prerequisiteText::CSV_XS 0.32 not found.
[Thu Aug  5 05:07:41 2010] Makefile.PL: Warning: prerequisite XML::RSS1.31 not found.
Writing Makefile for koha
koha@li190-245:~/kohaclone$

You will need to look up these modules in your distribution's repositories to find corresponding packages. The system packages will usually be named with a prefix "perl-" and will have "-" instead of "::". As an example, the Perl module PDF::Reuse::Barcode should have a corresponding Perl package called perl-PDF-Reuse-Barcode.

If you don't find some of the modules in your distribution's sources, then those modules will need to be installed using CPAN.

Debian/Ubuntu package lists

Package lists are available for Debian and Ubuntu in the kohaclone folder:

koha@li190-245:~/kohaclone$ vi install_misc/debian.packages

koha@li190-245:~/kohaclone$ vi install_misc/ubuntu.packages

If you are on another distribution use the debian.packages or ubuntu.packages lists to look for corresponding modules in your distribution's sources.

It is important to note that these lists may not be completely accurate. This is because software changes all the time; for instance a package that was hitherto unavailable in Debian sources may become available when a new Debian version is released. So it might be a good idea to look for additional Perl packages in your Linux sources before installing them using CPAN.

Setting up repositories or sources

You might need to configure additional repositories or sources for some of the packages in your installation list.

With Debian you will need to add Index data's sources for YAZ related packages. Edit the sources file:

koha@li190-245:~$ sudo vi /etc/apt/sources.list

And add these lines to set up Index data's Debian package sources:

# Index Data 
deb http://ftp.indexdata.dk/debian lenny main
deb-src http://ftp.indexdata.dk/debian lenny main

With openSuSE 11.2, you will need the Perl repository:

http://download.opensuse.org/repositories/devel:/languages:/perl/openSUSE_11.2/

We use zypper to add a repository from the command line:

koha@li190-245:~$ sudo zypper ar http://download.opensuse.org/repositories/devel:/languages:/perl/openSUSE_11.2/ perl-repository

Don't forget to refresh the package source. On Debian:

koha@li190-245:~$ sudo apt-get update

On openSuSE:

koha@li190-245:~$ sudo zypper refresh

Configuring the CPAN shell

We will need to configure the CPAN shell before we can use it to install Perl modules. To launch the shell we use the cpan command:

koha@linux:/home/koha/kohaclone # sudo cpan

You can choose to configure CPAN automatically:

Would you like me to configure as much as possible automatically? [yes] yes

Or you can run through the steps manually.

Once the configuration completes, you should be in the CPAN shell:

commit: wrote '/usr/lib/perl5/5.10.0/CPAN/Config.pm'Exiting subroutine via last at /usr/lib/perl5/5.10.0/CPAN.pm line 1450, <STDIN> line 1.
cpan shell -- CPAN exploration and modules installation (v1.9205)ReadLine support enabled
cpan[1]>

Installing Koha's software stack

In this final section we demonstrate the installation steps on Debian and openSUSE.

Installing packages using the package manager

We will install most packages using the package manager. Having installed Git in an earlier section, readers are already familiar with the commands used to install individual packages; in this section, we also look at ways of speeding up the process.

Installing packages from the Linux prompt

You can install the packages one-by-one like this:

koha@li190-245:~/kohaclone> sudo apt-get install apache2

On openSuSE, the command would look like this:

koha@li190-245:~/kohaclone> sudo yast -i apache2

Or you can install multiple packages in one statement:

koha@li190-245:~/kohaclone> sudo apt-get install apache2 mysql make gcc

Or:

koha@li190-245:~/kohaclone> sudo yast -i apache2 mysql make gcc

Installing packages using shell scripts

To speed up the installation, you can write a shell script file that looks like this:

yast -i apache2 \
mysql \
make \
gcc \
yaz \
libyaz \
libyaz-devel \
perl-Algorithm-CheckDigits \
perl-Biblio-EndnoteStyle \

And execute this script using the sh command:

koha@li190-245:~> sudo sh yast-opensuse-perl.sh

Installing packages using dselect

Debian and Ubuntu users can use dselect, a convenient way to install package lists.

First we install dselect:

koha@li190-245:~/kohaclone$ sudo apt-get install dselect

Next, we select what needs to be installed by pointing to the file containing the list of packages:

koha@li190-245:~/kohaclone$ sudo dpkg --set-selections < install_misc/debian.packages

Finally we install the selected packages:

koha@li190-245:~/kohaclone$ sudo dselect

From the dselect screen, we will need to execute the install, configure, and delete options in sequence.

Installing Perl modules using CPAN

We use the CPAN shell to install only those Perl modules that are not available in your distribution's sources.

We can install such modules from inside the CPAN shell, like this:

koha@li190-245:~/kohaclone$ sudo cpan
cpan[1]> install HTTP::OAI

Install multiple modules using a single statement:

cpan[2]> install IPC::Cmd Net::LDAP Net::LDAP::Filter 
Net::Z3950::ZOOM Text::CSV::Encoded

Another way of doing it is from the Linux shell:

koha@li190-245:~> sudo cpan HTTP::OAI

Here is how we install modules from the Linux shell:

koha@li190-245:~> sudo cpan IPC::Cmd Net::LDAP Net::LDAP::Filter 
Net::Z3950::ZOOM Text::CSV::Encoded

Troubleshooting CPAN installations

If CPAN modules don't install successfully, we would see messages like these at the end of install command:

MIRK/Net-Z3950-ZOOM-1.26.tar.gz              : writemakefile NO
'/usr/bin/perl Makefile.PL INSTALLDIRS=site' returned status 512
 WRW/Barcode-Code128-2.01.tar.gz              : make_test NO
 LARSLUND/PDF-Reuse-Barcode-0.05.tar.gz       : make_test NO one
dependency not OK (Barcode::Code128)
cpan[8]>

From the messages above, we learn that the module Net-Z3950-ZOOM has failed at the Makefile.PL stage likely due to missing prerequisites.

The module PDF-Reuse-Barcode has failed to install, because one of its prerequisites—Barcode::Code128 has failed at the make test stage.

To troubleshoot such problems we need to look at error messages for clues. Resolve any problems that are found and then install each module manually using the make set of commands.

As an example, let us troubleshoot problems with installing the module Net-Z3950-ZOOM.

We use the look command to get into a Linux subshell:

cpan[8]> look Net::Z3950::ZOOM
Running look for module 'Net::Z3950::ZOOM'
Trying to open a subshell in the build directory...
Working directory is /home/koha/.cpan/build/Net-Z3950-ZOOM-1.26-C9NuSo

We run make clean to start afresh:

sh-3.2# make clean
make: *** No rule to make target 'clean'.  Stop.

Next run the Makefile.PL program:

sh-3.2# perl Makefile.PL

At this stage we see an error message indicating missing system packages:

ERROR: Unable to call script: yaz-config
If you are using a YAZ installation from the Debian package "yaz", you
will also need to install "libyaz-dev" in order to build this module.

This means we need to install YAZ related packages using the package manager, on Debian—yaz and libyaz-dev and on openSUSE—yaz, libyaz, libyaz-devel.

After installing these packages using the package manager, we run the make series of commands to complete the installation:

cpan[8]> look Net::Z3950::ZOOM
sh-3.2# make clean
sh-3.2# perl Makefile.PL
sh-3.2# make
sh-3.2# make test
sh-3.2# make install
sh-3.2# exit
cpan[8]>

Setting up Koha's MySQL database

Before we install Koha, we need to setup Koha's MySQL database and a MySQL user with privileges over the database.

Unless you have already done this as part of the installation, we first secure MySQL by configuring a password for the root users:

koha@li190-245:linux:/home/koha # mysqladmin -u root password 'yourdbrootpasswd';

koha@li190-245:~/kohaclone$ mysql -u root -pEnter password:

Create Koha's database:

mysql> create database koha;

Create a MySQL user for Koha's database and grant it privileges. Both actions are accomplished with one command:

mysql> grant all on koha.* to 'kohaadmin'@'localhost' identified by 'katikoan';
mysql> flush privileges;
mysql> quit

Configuring Koha's installation: Makefile.PL

After we have installed required system and Perl packages and set up the database, we are ready to install Koha. The first step is to run Makefile.PL to configure Koha's installation. We will need to supply responses to questions such as mode of installation or database name:

koha@linux:/home/koha/kohaclone # perl Makefile.PL

Enter responses to configuration questions as follows:

Installation mode should be dev if you wish to use Git to apply patches.

Installation mode (dev, single, standard) [standard] dev

User koha must have write access to the configuration directory to avoid permissions problems:

Configuration directory: [/home/koha/koha-dev]

Choosing mysql, Postgre support in Koha is experimental:

DBMS to use (Pg, mysql) [mysql]

Here we specify the name of the database we created in an earlier step:

Please specify the name of the database to be used by Koha [koha]

Specify the MySQL user that has privileges over the database; we created this user in an earlier step:

Please specify the user that owns the database to be used by Koha [kohaadmin]

Specify the password of this user:

Please specify the password of the user that owns the database to be used by Koha [katikoan] katikoan

Say yes to Zebra – Koha's powerful catalog search engine; Although Koha can function without Zebra by using database indexes, Zebra's superior capabilities make it an important part of your installation:

Install the Zebra configuration files? (no, yes) [yes]

For other questions, the default value should be fine. Simply press the Return key to proceed to the next step.

The program display a summary of the configuration at the end, make a note of the details:

Koha will be installed with the following configuration parameters: 
DB_HOST  localhost 
DB_NAME  koha 
DB_PASS  katikoan 
DB_PORT  3306 
DB_TYPE  mysql 
DB_USER  kohaadmin 
INSTALL_BASE  /home/koha/koha-dev 
INSTALL_MODE dev 
INSTALL_ZEBRA  yes 
KOHA_INSTALLED_VERSION  3.01.00.124 
RUN_DATABASE_TESTS   no 
USE_MEMCACHED  no

If you have installed all prerequisites you should not see warning messages of missing prerequisites. If you do, you should go back and install any missing modules. Rerun Makefile.PL till all warnings disappear.

Completing Koha's installation

Run the following commands to complete the installation of Koha:

koha@li190-245:~/kohaclone$ make
koha@li190-245:~/kohaclone$ make test
koha@li190-245:~/kohaclone$ sudo make install

Koha 3 Library Management System: Install, configure, and maintain your Koha installation with this easy-to-follow guide

What do you get with eBook?

Product Details

Key benefits

Description

What you will learn

What do you get with eBook?

Product Details

Packt Subscriptions

Table of Contents

Recommendations for you

Customer reviews

Filter reviews by

People who bought this also bought

Authors (3)

FAQs