Install Koha on Ubuntu — Part 3: Koha Prerequisites

Koha Logo

Warn­ing: this tuto­r­i­al was devel­oped in 2008, and is for ver­sions of Koha and Ubun­tu that are now con­sid­ered quite old. If you want to install the cur­rent ver­sion of Koha on Ubun­tu, please vis­it Koha on Ubun­tu at the Koha Com­mu­ni­ty wiki.

This is part 3 of 6 in a tuto­r­i­al series on installing Koha 3.0 on Ubun­tu 8.10.

This arti­cle cov­ers installing a wide vari­ety of under­ly­ing soft­ware pack­ages that Koha requires. These mod­ules are the foun­da­tion upon which Koha is built. You’ll also down­load the actu­al Koha soft­ware so you can install it in the next arti­cle.

If you plan to put Koha into pro­duc­tion for real-world Library use there are many oth­er things you need to con­sid­er. The final arti­cle in the series, Going Live, dis­cuss­es this fur­ther.

Who this arti­cle is for.
  • Peo­ple who want to try Koha.
  • Peo­ple who aren’t nec­es­sar­i­ly Lin­ux experts, but…
  • Who are very com­fort­able with com­put­ers and not afraid of using a com­mand-line inter­face.
What to expect.

Install Required Packages

Download Koha Source Files

First down­load and unpack the Koha 3.0 source files, mak­ing your­self root if you aren’t already. If you’re using a lat­er ver­sion of Koha you’ll need to update the ver­sion num­ber appro­pri­ate­ly in the file and direc­to­ry names below.

sudo su
cd /build
tar -xzvf koha-3.00.00.tar.gz
cd koha-3.00.00

You need to have the Koha files in place for a step in the next sec­tion. How­ev­er, it’s also worth not­ing that the Koha direc­to­ries include two files with instal­la­tion instruc­tions:

  • /build/koha-3.00.00/INSTALL
  • /build/koha-3.00.00/INSTALL.debian

These are valu­able resources, and this guide is based in part upon their con­tents. How­ev­er, depend­ing upon your back­ground you might find the INSTALL files cryp­tic at times since they assume a cer­tain lev­el of under­stand­ing of Lin­ux and Koha.

Also, the INSTALL files are final­ized before the Koha release becomes gen­er­al­ly avail­able. Once any soft­ware release is in gen­er­al dis­tri­b­u­tion peo­ple will inevitably find a vari­ety of new prob­lems and nec­es­sary tweaks. Res­o­lu­tions to these issues might be post­ed on per­son­al web pages or the Koha Mail­ing List—too late for inclu­sion in the INSTALL files. I’ve includ­ed the rel­e­vant res­o­lu­tions I’m aware of in this guide.

Even so, the INSTALL files are worth review­ing in gen­er­al, and are par­tic­u­lar­ly impor­tant resources if you hit prob­lems dur­ing the instal­la­tion process.

And if you’re installing a ver­sion of Koha after 3.00.00 you real­ly must read these files care­ful­ly in case of sig­nif­i­cant changes to the instal­la­tion process.

Prepare for Package Installation

We’re about to use the apt-get util­i­ty to install a num­ber of depen­den­cies. Before doing this we need to tell apt-get where it can find the pack­ages. Edit the list of pack­age sources:

gedit /etc/apt/sources.list

Add the fol­low­ing lines to the sources.list file then save and quit:

deb etch main
deb-src etch main

You also need to down­load a dig­i­tal­ly signed key to let apt-get hap­pi­ly use these sources. You could com­plete the install with­out this key but you would get some error mes­sages telling you the sources you’ve added aren’t trust­ed.

cd /build
apt-key add indexdata.asc

Then refresh your list of avail­able pack­ages. This com­mand should com­plete with­out error mes­sages.

apt-get update

Install the Packages

For­tu­nate­ly the Koha source includes a pack­age list that lets you install the major­i­ty of the required pack­ages with­out see­ing the details.

cd koha-3.00.00
dpkg --set-selections install_misc/debian.packages

Next install the dse­lect mod­ule and run it:

apt-get install dselect

Choose [I]nstall to install the pack­ages.

Instal­la­tion of the pre­req­ui­sites will take a good while—at least sev­er­al min­utes. You may receive one or more prompts dur­ing the instal­la­tion process, so keep an eye on it peri­od­i­cal­ly.

When you’re asked whether to delete pre­vi­ous­ly down­loaded .deb files, accept the default of Y. Then:

  1. Choose [C]onfigure.
  2. Choose [R]emove.
  3. Choose [Q]uit.

Next you’ll need to install a few pack­ages indi­vid­u­al­ly:

apt-get install libexpat1-dev
apt-get install idzebra
apt-get install libgd2-xpm-dev
apt-get install libgdbm-dev

Install Required Perl Modules

Next we need to install a num­ber of Perl mod­ules that Koha requires. With one excep­tion we’ll do this using the cpan instal­la­tion util­i­ty.

Install Net::LDAP Manually

As of this writ­ing one of the mod­ules, Net::LDAP, can’t be installed via cpan. We’ll need to install it man­u­al­ly.

If this (or any oth­er) CPAN URL no longer exists, the pack­age has prob­a­bly been replaced with a new one. You can find the new pack­age URL by vis­it­ing and search­ing for the pack­age name with­out the ver­sion num­ber (for exam­ple, “CGI-Ses­sion”). The package’s page will list the new download’s name; prob­a­bly only the ver­sion num­ber has changed.

Note that the wget com­mand below is a long line and might wrap in your brows­er. That won’t cause a prob­lem if you copy and paste the text, but will be con­fus­ing if you man­u­al­ly copy the line.

cd /build
tar -xvzf perl-ldap-0.38.tar.gz
cd perl-ldap-0.38
perl Makefile.PL
make test
make install

Install Other CPAN Modules

The first time you run cpan you’ll see this prompt:

Would you like me to try to configure as much as possible automatically?

Say “Yes” unless you’re a Lin­ux expert and/or a bit of a con­trol freak. cpan’s auto­mat­ic set­tings should gen­er­al­ly work well.

Note: as the text before this prompt hints rather cryp­ti­cal­ly, if you have trou­ble with cpan after using the auto­mat­ic set­up you can re-run the con­fig­u­ra­tion script lat­er, spec­i­fy­ing the set­ting man­u­al­ly.

The help text is unclear on how to re-run the con­fig­u­ra­tion script. Here’s how.

Remem­ber: you only need to do this lat­er if cpan seems bro­ken.

perl -MCPAN -e shell
cpan> o conf init
[Configuration happens here.]
cpan> exit

A Note on cpan Diagnostic Messages

Installing a sin­gle CPAN mod­ule can gen­er­ate screen after screen of diag­nos­tic mes­sages, and we’re about to install lots of pack­ages at once. You will quite lit­er­al­ly be exposed to thou­sands of lines of diag­nos­tic mes­sages.

Good news: most mes­sages mean some­thing went right. You can ignore these.

Bad news: some mes­sages mean some­thing went wrong. Hope­ful­ly you won’t get any of these, but if you do you need notice and read them to help you trou­bleshoot the prob­lem. Giv­en the mod­ule name and error mes­sage you can search the inter­net for exist­ing solu­tions and, if you find none, you can post your ques­tion to the Koha Mail­ing List.

Worse news: giv­en num­ber of mes­sages you’re about to see it’ll be imprac­ti­cal to read every one and decide whether it’s a hap­py mes­sage or an unhap­py mes­sage.

Good news again: it’s gen­er­al­ly ok if you don’t notice an error mes­sage. Why? In a few min­utes when you install Koha it will check whether all the required pack­ages are in place. If there was a prob­lem installing one or more of them, Koha will give you a list of miss­ing mod­ules. At that point you can go back and install the offend­ing mod­ules indi­vid­u­al­ly and watch more close­ly for error mes­sages. For exam­ple, if Koha reports a prob­lem with the Text::CSV mod­ule, while still logged in with root priv­i­leges enter “cpan Text::CSV” to install that mod­ule man­u­al­ly.

Install the Perl Modules

Enter the fol­low­ing com­mand includ­ing the back­slash­es (“\”). This is sim­ply one long cpan com­mand to install a long list of Perl mod­ules. The back­slash­es let you hit return and keep typ­ing with­out actu­al­ly exe­cut­ing the com­mand. The sim­plest thing is to copy and paste these lines into your ter­mi­nal win­dow.

cpan YAML CGI::Session CGI::Session::Serialize::yaml \
MARC::Record Class::Accessor MARC::Charset MARC::File::XML \
Net::Z3950::ZOOM HTML::Template::Pro HTML::Scrubber \
MARC::Crosswalk::DublinCore PDF::Reuse PDF::Reuse::Barcode \
Email::Date SMS::Send Text::CSV Text::Iconv Data::ICal GD \
GD::Barcode::UPCE XML::RSS Algorithm::CheckDigits::M43_001 \
Biblio::EndnoteStyle POE Schedule::At XML::LibXML::SAX::Parser

As with the ear­li­er depen­den­cy instal­la­tion, this one will take a good long while. The dif­fer­ence is that this one will ask you many questions—see the cpan rules of thumb above for guid­ance on answer­ing them. Some­times you’ll get sev­er­al ques­tions in a row and some­times you’ll wait sev­er­al min­utes between ques­tions.

This means you’ll need to keep fair­ly close watch on the process for a good long while even though for most of the time you won’t be doing any­thing. (Fill­ing this time is what MP3 play­ers are for.)

Next Section…

Part 4: Koha

Registration is required to comment.

You aren't currently logged in. You can use the fields below to post a comment without logging in or registering, or you can log in or register now.

By submitting a comment here you grant Blazing Moon a perpetual license to reproduce your words and name/web site in attribution. Inappropriate comments will be removed at admin's discretion.

Blazing Moon RSS Feed