Blazing Moon

Installing Koha 3.0 on Ubuntu 8.10

Perl Modules

Comprehensive Perl Archive Network (CPAN)

CPAN is a repository for Perl modules and other Perl resources, and the cpan utility is a streamlined way to install them. Rather than entering a series of commands manually (as in the Net::LDAP example on this page), cpan lets us enter a single command. Even better, if we want to install multiple modules we can string their names together in a single command.

Next we need to install a number of Perl modules that Koha requires. With one exception we'll do this using the cpan installation utility.

Install Net::LDAP Manually

As of this writing one of the modules, Net::LDAP, can't be installed via cpan. We'll need to install it manually.

If this (or any other) CPAN URL no longer exists, the package has probably been replaced with a new one. You can find the new package URL by visiting http://search.cpan.org and searching for the package name without the version number (for example, "CGI-Session"). The package's page will list the new download's name; probably only the version number has changed.

cd /build
wget ftp://ftp.perl.org/pub/CPAN/authors/id/G/GB/GBARR/perl-ldap-0.38.tar.gz
tar -xvzf perl-ldap-0.38.tar.gz
cd perl-ldap-0.38
perl Makefile.PL
make
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 Linux expert and/or a bit of a control freak. cpan's automatic settings should generally work well.

Note: as the text before this prompt hints rather cryptically, if you have trouble with cpan after using the automatic setup you can re-run the configuration script later, specifying the setting manually.

The help text is unclear on how to re-run the configuration script. Here's how.

Remember: you only need to do this later if cpan seems broken.

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

A Note on cpan Diagnostic Messages

Installing a single CPAN module can generate screen after screen of diagnostic messages, and we're about to install lots of packages at once. You will quite literally be exposed to thousands of lines of diagnostic messages.

Good news: most messages mean something went right. You can ignore these.

Bad news: some messages mean something went wrong. Hopefully you won't get any of these, but if you do you need notice and read them to help you troubleshoot the problem. Given the module name and error message you can search the internet for existing solutions and, if you find none, you can post your question to the Koha Mailing List.

Worse news: given number of messages you're about to see it'll be impractical to read every one and decide whether it's a happy message or an unhappy message.

Good news again: it's generally ok if you don't notice an error message. Why? In a few minutes when you install Koha it will check whether all the required packages are in place. If there was a problem installing one or more of them, Koha will give you a list of missing modules. At that point you can go back and install the offending modules individually and watch more closely for error messages. For example, if Koha reports a problem with the Text::CSV module, while still logged in with root privileges enter "cpan Text::CSV" to install that module manually.

Install the Perl Modules

cpan for Koha: Rules of Thumb

  1. Only install optional modules if you're sure.
  2. Accept default responses unless you're sure.
  3. If cpan asks to add modules due to "unsatisfied dependencies" or the like, say Yes.
  4. If you're unsure whether a specific package installed correctly just reinstall it. If all is well cpan will tell you the package is up-to-date.

Enter the following command including the backslashes ("\"). This is simply one long cpan command to install a long list of Perl modules. The backslashes let you hit return and keep typing without actually executing the command. The simplest thing is to copy and paste these lines into your terminal window.

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 earlier dependency installation, this one will take a good long while. The difference is that this one will ask you many questions—see the cpan rules of thumb above for guidance on answering them. Sometimes you'll get several questions in a row and sometimes you'll wait several minutes between questions. This means you'll need to keep fairly close watch on the process for a good long while even though for most of the time you won't be doing anything. (Filling this time is what MP3 players are for.)