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.
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
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
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
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
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
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 makemake: This compiles the software and creates executablesmaketest: It runs test cases to ensure proper installation, flags errors, and warnings in case of problemsmakeInstall: This installs the executable files into proper directories in the server
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/.
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.
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.
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.
In this section we prepare for the installation—setting up a server, preparing a list of packages for installation and configuring installation tools.
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. |
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.
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
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 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.
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
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.
Package lists are available for Debian and Ubuntu in the kohaclone folder:
koha@li190-245:~/kohaclone$ vi install_misc/debian.packages
Or
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.
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
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]>
In this final section we demonstrate the installation steps on Debian and openSUSE.
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.
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
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
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.
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
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]>
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
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.
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.