Koha 3 Library Management System

By Savitra Sirohi , Amit Gupta
    What do you get with a Packt Subscription?

  • Instant access to this title and 7,500+ eBooks & Videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Free Chapter
    Installing the Software Stack
About this book

Koha is the first full-featured open source library management system that is widely used for efficiently managing libraries. However, setting up and maintaining Koha is no walk in the park. It is not as straightforward as setting up the other popular LAMP applications.

This practical guide provides all the essential information that is needed to make the task of installing and configuring Koha really seem simple and easy. It demonstrates how to set up Koha and its various aspects – installation, configuration, application administration, and data migration. It also covers troubleshooting, software maintenance, software customization, and other advanced topics.

The book starts with installing and configuring the LAMP stack and the Koha application to meet your needs. It then goes deeper into setting up various rules and configuring settings for Koha. It also covers data migration of catalog records, software maintenance, and customization of the application. Chapters are also dedicated to providing an insight into advanced topics such as LDAP integration and Internationalization. Filled with numerous code samples and screenshots, this book will tour you through setting up Koha for evaluation or test purposes. It also includes loads of tips for troubleshooting and maintenance activities.

By the end of this book, you will have gained the knowledge to get the most out of your Koha installation.

Publication date:
November 2010


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 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:




2 GB RAM, 40 GB hard disk should be good for most libraries.

Internet connection

High speed Internet connection to download software.


Your preferred distribution installed on the server.

Firewall ports opened

Git port 9418

FTP port 21

HTTP port 80


Access to the server via SSH, or directly.


A Linux user with sudo privileges, in this book we use user—koha.


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:




The web server.


The database server.


Programs that helps build and install packages.


Is the compiler package.


Is the toolkit used in Z39.50 clients and servers.


YAZ related libraries.


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

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:


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

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


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)

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

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';

Log in to MySQL using root:

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 

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


Here is what we learned in this chapter:

  • Using Git to download and use a certain version of Koha

  • Preparing an installation list for your distribution

  • Installing packages using the package manager

  • Installing Perl modules using the CPAN shell

  • Troubleshooting Perl module installations

  • Setting up Koha's MySQL database

  • Installing Koha using the Make utility

In the next chapter, we will learn how to configure the Apache web server and Koha's web installer.

About the Authors
  • 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.

    Browse publications by this 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.

    Browse publications by this author
Koha 3 Library Management System
Unlock this book and the full library FREE for 7 days
Start now