Koha Installation

The instructions contained here refer to Installation of Koha on clean Debian. This information was created in a hurry, in case of doubts always consult.


Key steps and Issues
Shalom Research & Documentation Center –
October 3/4, 2008
• Open Source software, including Koha are not
regarded “easy” to install.
• Koha is regarded as the most difficult to
Always Remember …
• Choosing open-source software is not
buying a pig in a poke
• No license cost but still some IT budget
(server), A librarian with good computer
literacy can install PMB but an ICT will
be required for others
• Time and obstinacy, have to find
workaround to solve some problems
• Commercial firms sell services for Open-
source ILS
Begin with the end in mind …Now to the Installation…..Overview of the Installation
– Web server (apache_2.0.63)
– Database server (mysql-4.0.18 / mysql-
4.1.22 /MySQL 5)
– Scripting Language (ActivePerl-
– 3.00.00 (ALPHA)
• Accessing Koha
• Post-installation Configurations &
• Back-up and security
Building Blocks
Networked Environment, LAN and
1                  Internet
A Good Computer or Server Machine
2                  Min. requirements usually determined
By the expected min no. of connected
An Operating system – Linux (Open Su
3                  Ubuntu, Debian, Mandrake, Redhat e.
Comfort at the command-line is
Extremely important
Choosing the O.S : operating System
Market Share
• IDC figures for OS on new server
shipments 3Q 2007:
• Windows Server: 67.1%
• Linux:           22.8%
– Slight gain for Windows/loss for Linux over
previous quarter
NB: KOHA was originally meant to run on Linux,
and some modules are not completely ported
into windows yet !
• Installing DFS enables you to really
understand how the linux installation
process works and allows you to control
what is installed where in the new
system. This level of control makes it
really suited for servers because there is
no unwanted service installed on the
system which makes it easier to harden
the system.
• GO to http://linux.suramya.com/tutorials/Install_DFS/
• Download Debian Image from
• ISO image for the i386 platform or a 338
MB ISO image for the Alpha platform and
burn CD.
• Find out the details on all the hardware
installed on the system (video card,
Network card, USB devices (Keyboard,
mouse etc)
• Details on your monitor including the
scan rate and the max screen resolution
supported etc.
• Get basic information on your network
setup – find out what your Gateway IP,
Subnet mask and DNS server IP’s are
• If you have an existing linux server on
the same network you can get this
information from the /etc/resolv.conf file
and the /etc/network/interfaces file.
• decide what mirror we will be using to
download packages from when we use
apt-get to install new software (You can
copy the /etc/apt/sources.list file from an
existing debian installation)
Starting the DFS install
• Insert the CD you created from the ISO
image in your CD-ROM and tell your
computer to boot from it. If your
computer doesn’t boot from the CD-ROM
when your restart it
• choose the kernel you want to use in the
new system.
Grub Boot screen for DFS     DFS install
• You will be prompted for a username,
enter ‘root’ (Without the quotes) as the
username and press enter, if you are
prompted for a password just hit enter.
DFS install
• Perform a general hardware detection by
running the following command: invoke-
rc.d discover start
• Run the following command to detect the
USB devices present on the system:
invoke-rc.d hotplug start
• Enable Ethernet (Use this cmd for DHCP)
: ifup eth0
• If you are not using a DHCP server or are
planning to give the new system a static IP you
need to edit the /etc/networking/interfaces file
and add the following lines to it:
Enable Ethernet
iface eth0 inet static
• Replace the IP’s in the above example with the
correct values for your network
• Edit the /etc/resolv.conf file and add the
following line to it:
• save the changes and activate the network by
running the following command:
ifup eth0
• Run /sbin/ifconfig to make sure that the network
card came up properly.
Partitioning, formating and
mounting the hard drive
• DFS includes both fdisk and cfdisk for
this process. cfdisk is a lot simpler than
fdisk so we will be using it to partition
the drive. Run this cmd:
cfdisk /dev/hdx
• Where /dev/hdx is the drive you are
parititioning. So if you are partitioning
hda (The master drive on IDE0) we would
run the following command:
cfdisk /dev/hda
cfdisk user interfaceCreate your partitions using cfdisk
• At a minimum a swap and a ‘/’ (Root)
partitions are required. Format the /
partition to ext3 (or ext2) using the
following command (Where /dev/hda2 is
your root partition. Replace this with the
appropriate device id for your system):
mkfs.ext3 /dev/hda2
• once the partition is formated we mount
it for read-write access by issuing the
following command:
mount /dev/hda2 /mnt
Initialize Partitions
• Next we need to initialize the swap
partition by issuing the following
command (Where /dev/hda1 is your swap
mkswap -f /dev/hda1
• and mount the swap partition using:
swapon /dev/hda1
If you don’t get any errors, proceed to the
next step of the install.
Install the basic system
• Install a very basic Debian install by
issuing the following command:
cdebootstrap sid /mnt file:///opt/packages
• This command install’s Debian sid in the /mnt
directory without using any package tools like
apt or dpkg. This step will take some time so you
might want to go read a book while it finishes.
Configure DFS
• Copy the /etc/resolv.conf to /mnt/etc/resolv.conf
• and /etc/network/interfaces to
/mnt/etc/network/interfaces .
• Edit the /mnt/etc/apt/sources.list and add some
Debian mirror addresses to it. These mirror
locations will be used to download
packages we will be needing later in the
guide. A complete list of Debian mirror’s is
available at:
Configure DFS
• The kernel on the DFS cd is a good one
to start off with so we will install it on our
new system by issuing the following
cd /mnt/root
dpkg-repack kernel-image-2.6.11
• This creates a kernel-image-
2.6.11_dfs.1.0_i386.deb file in the
/mnt/root directory. Now we chroot to the
new install by issuing the following
command: chroot /mnt
Install new kernel
• We can install our new kernel by issuing
the following command:
dpkg -i root/kernel-image-2.6.11_dfs.1.0_i386.deb
• Run the following command to start the
network card and get an IP:
ifup eth0
• If you are trying to get a DHCP address
you might get an error message
complaining that /proc/net/dev doesn’t
exit. If thats the case then create the
directory by running the following
commands:mkdir /proc/net/ mkdir /proc/net/dev
Create a /etc/fstab file
• /etc/fstab tells the kernel what partitions
to mount and what locations they should
be mounted at.
You should modify the above example to point to the
correct partitions for your install.
Install Essential Packages
• Get a list of the latest packages available
from the debian mirrors listed in
/etc/apt/sources.list. by running the cmd
apt-get update
• The first package we need to install is
makedev which creates device files in
/dev. The following command will install
makedev on our system:
apt-get install makedev
• install procps which installs the /proc file
system utilities by issuing the following
cmd: apt-get install procps
Install and Configure Grub
•  apt-get install module-init-tools grub
• mkdir /boot/grub
• cp /lib/grub/i386-pc/* /boot/grub/ -R
• # Start the GRUB command line interface by
issuing the following command: grub
• # Tell GRUB where the root of our install is
located by running the following command
(This command tells GRUB that the root
partition is on the 2nd partition on the 1st
harddisk (hda2)): root (hd0,1)
• # Install the bootloader to the MBR (Master
Boot Record) by running the following
command: setup (hd0)
• quit update-grub
Edit the menu
• List file to make sure it points to the
correct kernel and partition. If any of
these locations are invalid the system
will halt with a kernel panic when re-
Complete Installation
• Now all we need to do is exit from the
chroot environment and reboot the
system. We do it by typing: exit
• At the command prompt followed by:
• Once the system reboots you should
remove the DFS disk and boot into the
new system. Keep in mind that this is a
very minimal install so you will need to
install a lot of packages. I suggest
installing openssh to allow you to access
the system remotely.
Do not forget…
• Change the root password on the new
system from the default value of blank to
something more secure.
• So far so good.
• With our Debian
OS now working
we begin setting
the right
platform for
Web server
Apache is considered as the
Biggest web server today.
At-least 80% of all web
Today runs on Apache, and
Number is increasing each
day, every hour
Web Server deployment
Source: Netcraft http://www.netcraft.com
How do you Install Apache?
• Just run this command:
apt-get install apache2 apache2-doc apache2-
mpm-prefork apache2-utils libexpat1 ssl-cert
• And that is all, you have Apache2 up and
• Install openssl using the following
#apt-get install openssl ssl-cert
Install PHP5 support for apache2
• #apt-get install libapache2-mod-php5 php5-cli
php5-common php5-cgi
• Once you install apache server you need
to Generate a certificate,Enable Apache
SSL support and Configure your SSL
• you need to use openssl from you
command prompt Use the following
command to generate certificates
• #openssl req $@ -new -x509 -days 365 -nodes
-out /etc/apache2/apache.pem -keyout
More on configuring ssl go to:
Encoding and Character Sets
• Be sure to have these lines in your
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
• We will have to configure Apache for
Koha later, but for now you should know
that Apache’s configuration files are kept
in /etc/apache/httpd.conf and Apache’s
log files are in /var/log/apache.
• Next we shall Install the Koha Database:
• MySQL is named after co-founder Monty
Widenius’s daughter, My. And it uses
Structured Query Language
• SQL is pronounced both “See-Kwel” and
# apt-get install mysql-server-4.1 or
# apt-get install mysql-server-5.0
• Then Set initial password
# mysqladmin password [password]
Server Configuration
• MySQL Version 4.1 is absolute minimum
if you want to handle encoding correctly
• Make sure you have the following in the
[mysqld] section of your my.cnf:
init-connect = ‘SET NAMES utf8’
• Connect to mysql as the (non-root) user
and type:
show variables;
Check to make sure the following
are set to utf8:
Preparing for CPAN & Perl
•Make sure that you proxy except the Koha
server while using CPAN.
•Install SSH server to allow remote login:
•# apt-get install ssh
•Download and configure Perl for your
system. You can safely answer any questions
the packaging system asks with the default
answers           # apt-get install perl
Getting ready for                              MCPAN
• Remaining Perl modules are not available via Debian’s
packaging system. But on the Perl network CPAN.
• But before we can install these modules we need to
install their dependencies which are outside of Perl.
# apt-get install unzip make lynx wget ncftp ftp less gcc
• Install ntpdate using apt-get:
# apt-get install ntpdate
• Or syncronize with your closest time server
# ntpdate
Installing Perl modules through
• # apt-get   install libdbi-perl
• # apt-get   install libdbd-mysql-perl
• # apt-get   install libdate-manip-perl
• # apt-get   install libhtml-template-perl
• # apt-get   install libmail-sendmail-perl
NB: Some of these perl modules have
other dependencies which must be
installed first, ensure you “follow” install
for those dependencies
Configuring Perl’s CPAN utility
• The first time you use Perl’s CPAN utility it will
configure itself.
# perl -MCPAN -e ‘install “Event”‘
• You should get the following message:
/usr/share/perl/5.6.1/CPAN/Config.pm initialized.
NB: 1. Accept Manual configuration
2. Policy on building prerequisites (follow, ask or
ignore)?     [ask]
3. Please enter your CPAN site: []
You can enter the following sites thusly:
Please enter your CPAN site: []
Enter another URL or RETURN to quit: []
Enter another URL or RETURN to quit: []
• As long as everything went smoothly
with the CPAN installation, Perl should
finish the install and return you to the
command prompt.
• We’re almost ready to install the
remaining Perl modules but one of them,
namely Net::Z3950, has a non-Perl
dependency that we need to install first
called Yaz.
The Yaz Toolkit
• Ensure the version of Debian you are using
can access the feed for latest YAZ tarball
from index data by first editing the
/etc/apt/sources.list file using the vim editor,
or nano
# vim /etc/apt/sources.list
• Add the following lines to the top of the file:
# for Yaz Toolkit
deb http://ftp.indexdata.dk/debian indexdata/sarge released
deb-src http://ftp.indexdata.dk/debian indexdata/sarge
• Now save the file and run
# apt-get update
YAZ TOOLKIT Installation
• If you get an error message try running
apt-get update again. If you keep
getting errors check the spelling of the
lines you just added in the sources.list
• Now run the following commands to
install the Yaz toolkit:
# apt-get install libyaz-dev
# apt-get install yaz-doc
Installing the MARC::Record
# apt-get install libdbi-perl libdbd-mysql-perl libdate-manip-
perl \
libhtml-template-perl libmail-sendmail-perl libmarc-record-
perl \
libxml-sax-perl libclass-accessor-perl libdate-calc-perl
Use CPAN to install the other Perl
dependencies (follow is recommended):
# perl -MCPAN -e shell
cpan> install Event MARC::Charset MARC::Lint Digest::MD5
GD::Barcode Data::Random PDF::Reuse::Barcode
cpan> get Net::Z3950
cpan> exit
Remember you might have to force install some modules
• At this point the most difficult part in installing
Koha is almost done. Some modules may have
to be installed later after running the Makefile
for Koha that checks whether all the
dependencies are installed. But for now we can
proceed and get KOHA.
• $ wget http://download.koha.org/koha-3.00.00-
• ( Note: use the latest stable version)
tar -zxvf koha-3.00.00.tar.gz
Run the Koha installer: $ perl Makefile.PL
( answer questions )      $ make
$ make test
$ sudo make install
NB: Please see the INSTALL.debian file in your download of
Koha. # cd koha-3.00.00/INSTALL.debian
• Follow the Installation instructions carefully,
especially on the database name – wrong
password for the database will terminate the
• Ensure Apache and MySQL are running at the
time of installation.
• All commands can be performed as a system
user with sudo privileges
Configure and start Apache
$ sudo ln -s /etc/koha/koha-httpd.conf
(note that the path to koha-httpd.conf may
be different depending on your
installation choices)
Add the following lines to
Listen 80
Listen 8080
Change Read/Write Permissions for
• Run the following commands:
$ sudo a2enmod rewrite
$ sudo a2ensite koha
$ sudo apache2ctl restart
Post-Installation Configurations
• Note: you may still see the usual Apache
default site if your VirtualHost
configuration isn’t correct. The
command “sudo a2dissite default” may
be a quick fix, but may have side-effects.
See the Apache HTTPD manual section
on virtual hosts for full instructions.
• see
• or visit the official Apache website for more
Starting Zebra
• Option 1: run the Zebra processes from the command
Zebra Server: $ sudo -u ${KOHA_USER} zebrasrv -f
• (note that the path to koha-conf.xml may be different
depending on your installation choices)
• Note: the user you run Zebra as will be the only user
with write permission on the Zebra index; in
development mode, you may wish to use your
system user.     Zebraqueue Daemon:
$ sudo
• Note: if you are running in this mode, you may wish
to defer starting the zebraqueue until you’ve run the
Starting Zebra: Option 2
• Run the Zebra processes as daemons, and add to startup
process: Note that references to $SCRIPT_DIR refer to the
directory where Koha’s command-line scripts are installed,
e.g., /usr/share/koha/bin.
• Zebra Server: $ sudo ln -s ${SCRIPT_DIR}/koha-zebra-ctl.sh
/etc/init.d/koha-zebra-daemon     (Note: ${SCRIPT_DIR} is
/usr/share/koha/bin/ by default in a standard install)
• $ sudo update-rc.d koha-zebra-daemon defaults ( Note: see
man chkconfig(8) on other distros )
• $ sudo ${SCRIPT_DIR}/koha-zebra-ctl.sh start
Zebraqueue Daemon: $ sudo ln -s ${SCRIPT_DIR}/koha-
zebraqueue-ctl.sh /etc/init.d/koha-zebraqueue-daemon
• $ sudo update-rc.d koha-zebraqueue-daemon defaults
• ( Note: see man chkconfig(8) on other distros )
• $ sudo ${SCRIPT_DIR}/koha-zebraqueue-ctl.sh start
Run the Web Installer
• Run the Web Installer, populate the database,
initial configuration of settings
• Point your browser to
• It should redirect you to the Web Installer where
you can continue the setup.
• You can install the sample data for libraries,
patrons, etc. via the Web Installer
wHAT Next?
• Once the installer has completed, you can import and
index MARC records from the command line thusly
(Note: you can also use the ‘Stage MARC records for
import’ from the Tools area of Koha’s Staff Client to
import a batch of MARC records):
$ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml
• (note: use the correct path to your koha-conf.xml)
• Import: Bibliographic data in MARC21 format
$ misc/migration-tools/bulkmarcimport.pl -file
• Authority data in MARC21 format
$ misc/migration-tools/bulkauthimport.pl -file
Fast Index
• $ misc/migration-tools/rebuild_zebra.pl -b -w
• Once the indexing has completed, you will be
able to search for records in your system.
NOTE: if you don’t run the Fast Index utility,
and you have the index updates scheduled as
per 7.3 the indexing process will happen in
the background, but it will be orders of
magnitude slower.
Schedule Index Updates
• Schedule regular index updates run
rebuild_zebra.pl -b -a -z as a regular cron job,
check misc/cronjobs/crontab.example for usage
• To enable public Z39.50/SRU servers, you’ll need
to edit your koha-conf.xml and change the
<listen> options to listen on a TCP port; then
restart the zebra daemon.
• If you are upgrading from a previous
installation of Koha 3, you can check how
to upgrade at http://www.koha.org
alternatively see information at
• Use Perl 5.8 (a library Koha depends
on,MARC::File::XML may not work with Perl 5.10,
• Your locale should be set to UTF-8, as should
Apache2 and MySQL 5. This step is VERY IMPORTANT
for a UNICODE compliant system. Please read over
the following document carefully:
IMPORTANT: You _MUST_ follow all the steps outlined
there for Apache2, MySQL 5, etc. BEFORE you install
• Set up apt sources for Git, Yaz and Zebra
packages Edit your /etc/apt/sources.list file and
add the following:
• # Index Data
deb http://ftp.indexdata.dk/debian etch main
deb-src http://ftp.indexdata.dk/debian etch main
# Backports
deb http://www.backports.org/debian etch-
backports main contrib non-free
Backports packages are signed with a key you can
install as follows:
$ sudo apt-get update
$ sudo apt-get install debian-backports-keyring
• The Index Data packages are signed with a key
you can install as follows:
$ wget
$ sudo apt-key add indexdata.asc
Run the following command to update your
$ sudo apt-get update
$ sudo apt-get -t etch-backports install git-core git-
$ sudo apt-get install yaz idzebra-2.0 idzebra-2.0-
• libgd Is not installed in barebones
debian, this might create a dependency
problem. Solution: sudo apt-get install libgd2-
• cpan Perl package install might work
smoothly, but could be problems with
installing some packages. SOLN: sudo cpan
Email::Date GD HTML::Scrubber SMS::Send
Text::CSV_XS Text::CSV Text::Iconv
• If you dont install libgb2, GD wont install
* the instructions did not mention when to
create the user ‘koha’:
sudo adduser koha
* we opt for having two domains (one for
OPAC and one for admin) instead of
using ports 80 and 8080. It was trivial to
affect this change in the koha-httpd.conf
• Download Koha via Git (optional)
$ git clone git://git.koha.org/pub/scm/koha.git
$ cd kohaclone
$ git checkout -b myinstall origin
• Note: for more information about Git,
please see the Koha Git Usage Guide:
• Test your SAX Parser and correct where necessary
You must be sure you’re using the XML::LibXML SAX
parser, not Expat or PurePerl, both of which have
outstanding bugs with pre-composed characters. You
can test your SAX parser by running:
• $ cd koha
• $ misc/sax_parser_print.pl
• You should see something like::
• If you’re using PurePerl or Expat, you’ll need to edit
your ini file, typically located at:
• Install DBD::mysql Perl module In order to handle
UTF-8 correctly, Koha requires at least version
4.004 of the DBD::mysql Perl module. However,
Debian Etch has a stable package only for
version 3.0008, so it is necessary to install the
module from CPAN. DBD::mysql’s test suite
needs to use a MySQL ‘test’ DB which doesn’t
exist anymore. So there are two options to install
• (1) install without test suite,
• (2) install with test suite requiring a test MySQL
DB creation.
• Install without test suite
Force install DBD::mysql:
$ sudo cpan
cpan> force install DBD::mysql
Instructions for installing using a test suite
can be found at http://git.koha.org/cgi-
;h=29808f4352f05d6e93e1e639d43949885c    eff0
Security and Backup
MySQL Administrator is a visual
administration tool for MySQL
database servers. To download and
Install go to
MySQL admin can be used from any
computer on the network to backup
the Koha database, and can be
included on Crontab to schedule
backups and for on-line automatic
backups. There versions for windows
and Linux available for downloading
Security and Backup
• Open Source software, available free
of charge
• Easy to use graphical interface,
Suitable for use on desktops, servers
and gateways
• Enables Internet connection sharing
& Allows you to define both inbound
and outbound access policy
• Option to whitelist or blacklist traffic
• Sets up DHCP for a local network Real
time firewall events view
• View active network connections,
including any traffic routed through
the firewall
• Advanced Linux kernel tuning
Security and Backup
• Ubuntu
Firestarter is available in the Ubuntu universe
To install, open the Applications menu and choose
Add/Remove.Select Show: All available
applications and search for Firestarter.
• Debian
Available through apt-get out of the box.
• Gentoo
Available through portage.
For more information go to
• Installing Koha might be a difficult affair
for newbies. Three things are required to
successfully complete this assignment:
1. Patience
2. Patience
3. Patience
Links & Other Resources
• KOHA documentation
• Version control using Git
• Debian Installation
• Bugs
• Mailing lists
• Email: bmugambi@gmail.com
• Call 0721-618073 / 020-386675
• Get more information on

10 Responses

  1. The whole process to install koha seems to take a large amount of time…say a full day of work. Have you ever heard of someone making an image of an installed koha system? seems like that would make some sense. I’m going at this install for the sixth time…I hope I can get it right this time. your instructions have been educational and should prove valuable to me. thanks for posting this.


  2. Vtsuag hi nice site thx http://peace.com

  3. First anything else, thank you very much by this contribution to the newbies community, we appreciate a lot your effort.

    Only one question please, I downloaded a virtual machine of KOHA 3.01 running in a Debian machine and after I followed the configure process via web, but in the end appear the message “configure your Zebra”, so I’m trying to do that but I could not found any documentation available except yours. And for me is a little confuse to understand what is exactly I need to do after configure koha via web to let Zebra run adequately. You are indicating to do a fast indexing process, exist any another thing that I need to consider?

    Thank you a lot in advance by your comments.


  4. I dont quite seem to understand your question properly, but to try and answer, is that you need to configure your Zebra on the administration- system-preferences side after installation. Especially the Z3950 Servers. If you have a problem in the Zebra installtion itself, then paste the error message here and we can try help out.

  5. It’s so much faster to simply install it from a Virtual Image downloadable on

    Install Ubuntu
    Install virtualbox
    Install Virtual Machine downloaded from the link provided (above)


  6. I would like to know the applications/making files for koha after completing all steps of istallation in windows server 2008.

  7. Please make a video tutorial of koha installation
    .This vill help new user like me 2 install koha in Ubuntu .If i know koha installation i will make video tutorial for all world……

  8. This is a great tip especially to those new to the blogosphere.
    Brief but very precise info… Thank you for sharing this one.
    A must read article!

  9. Hey there! Do you know if they make any plugins to safeguard against hackers?
    I’m kinda paranoid about losing everything I’ve worked
    hard on. Any recommendations?

  10. Any childs method of titanfall down load is usually crunchy externally but soft at the
    center. Each cruelty along with democracy are usually tried out and inhibited.
    ‘ The existance is a technology which meows ‘Hat instructions 20 dollar.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: