2004-12-15
| Revision History | ||
|---|---|---|
| Revision 2.0.0p1 | 2004-11-28 | jmf |
|
Generalized some of the language, reformated the text. My installing on debian manual is revised a bit for Koha 2.0 but does not include 2.2 stuff as I haven't installed 2.2 on debian yet. Also, I don't cover the actual Koha install--just the dependencies. I like that format as the installation of Koha is really the same once the dependencies are taken care of. -- jmf |
||
| Revision 2.0.0 | 2004-11-23 | |
|
XML version (prepared by Stephen Hedges) of webpage posted at http://kados.org/LibraryScience/koha.html for inclusion in Koha-related documents collection. Revision numbering change to conform to Koha documents standard practice. |
||
| Revision 0.9.2 | 2004-02 | |
|
Changes made by Joshua Ferraro. Fixed some more typos-thanks again to James Estep for pointing them out! Added info on 2.4 kernel version. Added info on proxy servers. Added directions for un-commenting Listen 8080. |
||
| Revision 0.9.1 | 2004-02 | |
|
Changes made by Joshua Ferraro. Fixed some typos-thanks to James Estep for pointing them out! |
||
| Revision 0.9.0 | 2004-02 | |
|
Changes made by Joshua Ferraro. |
||
| Revision 0.8.0 | 2003-06 | |
|
Initial release. |
||
By Joshua Ferraro
The current maintainer of this document is Joshua Ferraro (<jmf AT kados.org>). Please forward him any comments, additions or suggestions, and they will be considered for inclusion in future releases of this manual.
Abstract
This document contains installation instructions for Koha 2.0RC4 on Debian GNU/Linux 3.0 "stable" (woody). It also contains pointers to more information on how to make the most of your new Koha system.
Copyright 2003, 2004 Joshua Ferraro <jmf (at) kados.org>
This document is related to Koha and is licensed to you under the GNU General Public License version 2 or later (http://www.gnu.org/licenses/gpl.html). Koha-related documents may be reproduced and distributed in whole or in part, in any medium physical or electronic, as long as this copyright notice is retained on all copies.
You may create a derivative work and distribute it provided that you:
License the derivative work with this same license, or the Linux Documentation Project License (http://www.tldp.org/COPYRIGHT.html). Include a copyright notice and at least a pointer to the license used.
Give due credit to previous authors and major contributors.
Commercial redistribution is allowed and encouraged; however, the author would like to be notified of any such distributions.
No liability for the contents of this document can be accepted. Use the concepts, examples and information at your own risk. There may be errors and inaccuracies, that could be damaging to your system. Proceed with caution, and although this is highly unlikely, the author(s) do not take any responsibility.
All copyrights are held by their by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark. Naming of particular products or brands should not be seen as endorsements.
In this document I assume that you are running a standard installation of Debian GNU/Linux 3.0 "stable" (woody). If you need help setting up Debian on your machine please see the Debian installation manual available from http://debian.org.
If you already have some knowledge about Linux or other Unices it will be easier to understand this manual, however, no intermediate steps are necessary subsequent to the installation of Debian before beginning the installation. This guide is a "cookbook" for installing Koha on Debian.
It's generally a good idea to run Koha on it's own computer; however, if you only have one machine on which to work, running multiple programs (such as X-Windows, KDE, Sendmail, Koha, etc.) at the same time, shouldn't be a problem--things will just run slower. But keep in mind that it is not necessary to install a windowing system (X-Windows) to install Koha: installing Koha is done entirely from the command line. In fact, Koha will run much faster if only the programs necessary for its operation are installed on the server. One reason that Debian GNU/Linux is a good choice as a platform for Koha is the availability of minimal bootable CD images which allow one to install a bare-bones but functional version. The minimal CD image fits on a 8 cm (3 inch) CD-R/RW (they'll also work on 12 cm/5 inch CD-R/RW media) and can be downloaded from http://www.debian.org/CD/netinst/. This manual is written for a Debian installation that was done using the LordSutch.com ISOLINUX mini-ISO image which can be downloaded directly from http://www.phy.olemiss.edu/debian-cd/.
A brief note about the Kernel version is in order. If you install Debian with the default 2.2 kernel (by pressing enter when booting off the minimal install CD) there will be some dependency problems later on in the install with the Perl module Net::Z3950 that I haven't taken the time to diagnose. To avoid that problem be sure to install Debian using the 2.4 kernel. To install using the 2.4 kernel press F3 when you boot off the minimal CD and follow the instructions for installing the 2.4 kernel (type bf24 at the boot: prompt and press enter). Note that you may need to manually select the right drivers for your network card using this kernel version.
This guide assumes that the Koha server has a dedicated Internet connection -- a high-speed connection is best. It is possible to install Koha without a dedicated Internet connection, but this guide does not go into how to do that.
Note that if you have an Internet proxy you may have problems using the CPAN service (see below). Make sure that you proxy except the Koha server while using CPAN. If you don't have a proxy server setup one set up it may be your ISP. If you want to check whether there is a HTTP proxy between you and the Internet you can try out this test site: http://www.lagado.com/proxy-test. Running this test from any workstation on your network, you should be able to tell whether your network is being proxied (although sometimes the test won't find well configured proxies). If your Koha server is on the same LAN as your workstation, there's a good chance that it's being proxied as well.
If the machine on which you will install Koha is nearby you can log in locally to perform the install. But most folks find it more convenient to log in remotely using an SSH or a Telnet client. If you are running Windows you can start Telnet by clicking Start->Run from the start menu and typing telnet. Or you can download the free SSH program PuTTy from http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html. SSH is a more secure and robust terminal emulator standard and is a better choice.
For many of the commands it will be necessary to have super user privileges on the Koha server. However, it's generally not a good idea to log into your server directly as the root user. It's better to use the su utility to allow your regular user to obtain superuser privileges. For example:
jmf@koha:~$ su
password:
koha:/home/jmf#
The # tells you that your have root privileges. If you want to return to your regular user type exit.
In order to log in to your server via SSH it is necessary to install it on the server. Most of the software written for GNU/Linux (including several SSH servers and clients) has been packaged by the Debian project and can be installed via the Internet using packaging system utilities such as apt-get. To install the SSH server, log in to the server, obtain root privileges and type:
koha:/# apt-get install ssh
The packaging system will download the package and install and configure SSH on your server. Follow the directions (default answers are fine) and select "yes" when you are asked whether you wish to install the SSH server as well as the client.
Koha is built with a number of related open source web-based technologies which are sometimes designated with the acronym L.A.M.P. L.A.M.P. refers to Linux (the GNU/Linux operating system), Apache (a robust webserver application), MySQL (a Relational Database Management System using the SQL standard) and Perl/Python/PHP (three common scripting languages). Koha was originally designed for a GNU/Linux system running Apache and MySQL and is written almost entirely in Perl. In order to install and use Koha it is necessary first to install and configure these dependencies.
Part of the configuration of these dependencies includes installing dependencies of the dependencies.[1]Koha also uses several extended Perl modules not all of which are available through the Debian packaging system. So these modules must be installed using other methods. Fortunately, most of Koha's dependencies either come bundled in a standard installation of Debian GNU/Linux or can be installed via the Internet using Debian's packaging system.
The majority of Koha is written in Perl -- a high-level programming or scripting language. Perl's functionality and usefulness has been extended and enhanced through the development and free distribution of modules (programming libraries) within the Perl community. The vast majority of these modules are available through the Perl Network CPAN. Others are available for download from the module developer's website or ftp server. Many of these modules have also been packaged directly into Debian's packaging system.
Koha relies on several of these extended module libraries for it's functions and getting all of these modules set up can be the most challenging part of the Koha installation. First though, Perl itself needs to be installed. We can do this using Debian's apt-get utility.
Log in to the server via SSH as a regular user, obtain superuser privileges and type:
koha:/# apt-get install perl
The packaging system will download and configure Perl for your system. You can safely answer any questions the packaging system asks with the default answers.
Several of Perl's extended module libraries are available via the Debian packaging system. We can install those using the apt-get utility as follows:
koha:/# apt-get install libdbi-perl
koha:/# apt-get install libdbd-mysql-perl
koha:/# apt-get install libdate-manip-perl
koha:/# apt-get install libhtml-template-perl
koha:/# apt-get install libmail-sendmail-perl
One of the advantages to using Debian's packaging system is that all the dependencies of a program are automatically installed and configured -- this even applies to the Perl modules we just installed. However, the remaining Perl modules are not available via Debian's packaging system. But they are available on the Perl network CPAN. Perl has a utility that can be run to automatically install modules from CPAN and it's pretty good about keeping track of dependencies within Perl itself,[2] but it cannot handle dependencies outside the Perl base. So before we can install these modules we need to install their dependencies which are outside of Perl.
Fortunately all of the dependencies for the Perl modules (and for the Perl CPAN utility) can be installed using Debian's packaging system. Type the following after logging in and obtaining superuser privileges:
koha:/# apt-get install unzip
koha:/# apt-get install make
koha:/# apt-get install lynx
koha:/# apt-get install wget
koha:/# apt-get install ncftp
koha:/# apt-get install ftp
koha:/# apt-get install less
koha:/# apt-get install gcc
It's also a good idea to make sure that the server has the correct time as Perl's CPAN utility sometimes gets cranky when the time is wrong. One way to do this is to install a utility called ntpdate. ntpdate will query any of a number of accurate time servers around the world and reset the machine's clock to the correct time. You can install ntpdate using apt-get:
koha:/# apt-get install ntpdate
During the configuration of ntpdate you will be asked to enter a time server to query for the correct time information. There is a list of time servers on the Internet at http://www.eecis.udel.edu/~mills/ntp/clock2a.html You can find the time server closest to you and enter either its IP address or domain name when prompted. If you misstype you can always run the nptdate utility from the command line. For instance, I run
koha:/# ntpdate 198.82.162.213
periodically to set the time on my computer.[3]
The first time you use Perl's CPAN utility it will configure itself. So we can start that process by telling Perl to install the MARC::Record module from the CPAN network:
koha:/# perl -MCPAN -e 'install "MARC::Record"'
You should get the following message:
/usr/share/perl/5.6.1/CPAN/Config.pm initialized.
CPAN is the world-wide archive of perl resources. It
consists of about 100 sites that all replicate the same
contents all around the globe. Many countries have at
least one CPAN site already. The resources found on CPAN
are easily accessible with the CPAN.pm module. If you want
to use CPAN.pm, you have to configure it properly.
If you do not want to enter a dialog now, you can answer
'no' to this question and I'll try to autoconfigure. (Note:
you can revisit this dialog anytime later by typing 'o conf
init' at the cpan prompt.)
Are you ready for manual configuration? [yes]
The setup process will take a while. It should be safe to answer all the questions with the default answers. You can safely ignore the utilities' attempts to get you to upgrade or install other Perl modules but you should allow it to prepend prerequisites. You can also set it to automatically build Perl prerequisites without asking by typing follow at the following prompt:
The CPAN module can detect when a module that which you are
trying to build depends on prerequisites. If this happens,
it can build the prerequisites for you automatically
('follow'), ask you for confirmation ('ask'), or just
ignore them ('ignore'). Please set your policy to one of
the three values.
Policy on building prerequisites (follow, ask or ignore)?
[ask]
Eventually you may get the following message:
Please check, if the URLs I found in your configuration
file () are valid. The urllist can be edited. E.g. with
'o conf urllist push ftp://myurl/'
Could not fetch MIRRORED.BY
CPAN.pm needs at least one URL where it can fetch CPAN
files from.
Please enter your CPAN site: []
You can enter the following sites thusly:
Please enter your CPAN site: [] ftp://archive.progeny.com/CPAN/
Enter another URL or RETURN to quit: [] ftp://cpan.cse.msu.edu/
Enter another URL or RETURN to quit: [] ftp://cpan.pair.com/
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.
Unfortunately, Yaz was not packaged into the version of Debian we are using. However, the folks at Indexdata (http://indexdata.dk) have provided a package feed wherby it can be downloaded. But we have to do some configuration of our packaging system to use their feed. As root (use su) open the /etc/apt/sources.list file using the vim editor (or the editor of your choice; for a manual on using the vi editor see http://www.eng.hawaii.edu/Tutor/vi.html).
jmf@koha:/~$ su
Password:
koha:/home/jmf# vim /etc/apt/sources.list
This file contains a list of all the feeds that we are using for our packaging system. You will want to add the following lines to the top of the file:
# for Yaz Toolkit
deb http://www.indexdata.dk/debian indexdata/woody released
deb-src http://www.indexdata.dk/debian indexdata/woody released
Now save the file and run
koha:/# apt-get update
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 file.
Now run the following commands to install the Yaz toolkit:
koha:/# apt-get install libyaz-dev
koha:/# apt-get install yaz-doc
At this point we can install the other Perl modules:
koha:/# perl -MCPAN -e 'install "Event"'
koha:/# perl -MCPAN -e 'install "Net::Z3950"'
koha:/# perl -MCPAN -e 'install "Digest::MD5"'
That should take care of the Perl installation and configuration as well as all the modules. If we left any Perl modules out Koha will warn us when we run the install script and will give instructions on how to install them.
For a database Koha uses MySQL—a free SQL-query-based Relational Database Management System. The installation and basic configuration of MySQL on a Debian system is quite simple. More advanced topics such as database optimization and MySQL administration are documented online at http://www.mysql.com/doc/en/index.html. It would be well worth your while to familiarize yourself with the basic functionality and behaviour that you can expect from MySQL. Chapter 5, Database Administration, is especially relevant for using Koha.
Not surprisingly MySQL is available from Debian's packaging system:
koha:/# apt-get install mysql-server
You can safely answer all the questions with the default answers. But you may want to select yes when prompted as to whether MySQL should start upon boot.
It's a good idea to set the MySQL administrator password right away. You will need to have this password handy later in the installation so make sure you write it down. You can set the password from the command line thusly:
koha:/# mysqladmin password [type your new password here]
but leave out the brackets.
According to the Apache website, Apache has been the most popular web server on the Internet since April of 1996. Additionally, the October 2003 Netcraft Web Server Survey found that over 64% of websites on the Internet use Apache, making it more popular than all other web servers combined. You can see the survey at http://news.netcraft.com/. Additionally, you can find out more about the Apache Software Foundation on their website at http://www.apache.org/.
Apache can also be installed using apt-get:
koha:/# apt-get install apache
We will have to configure Apache for Koha later on in the install, 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.
Well, that's it, we've installed all the dependencies for Koha. The hardest part of the installation is over. Now you are ready to download Koha from http://www.koha.org and install it following the directions in the INSTALL file.
[1] and the dependencies of the dependencies of the dependencies, and the...
[2] i.e., some modules in Perl rely on other modules and Perl will make sure they are installed correctly.
[3] You can also run ntpdate and other periodic server tasks automatically using a utility called cron. For more information see the man page for cron.