Installing Koha 3 On Ubuntu Hardy Heron (8.04, LTS)

This guide was based on Installing Koha 3 Beta On Ubuntu Gutsy Gibbon (7.10) and the Installation Guide for Installing Koha 3 on openSUSE 11 entry.

This document describes installation with Ubuntu 8.04 LTS (either Desktop or Server). These instructions should not be expected to work with any later version of Ubuntu (like 8.10 or 9.04).

This guide assumes you installed off the Server install CD (ubuntu-8.04.1-server-i386.iso).

Perl applications can be a bit temperamental because of the plethora of dependencies. Be mindful of this during operating system updates (ie, don't upgrade the operating system unless you are prepared for Koha to break as a result).

FAIR WARNING: Ubuntu 8.04 ships with Perl 5.8, while later Ubuntu versions ship with later versions of Perl. A library Koha depends on, MARC::File::XML, may not work with Perl later than 5.8.

To confirm which Perl version your operating system uses:

$ perl --version

• This guide assumes you will execute all commands as a non-privileged user you create during install – as such all commands will be prefixed with sudo. You should REALLY avoid using the root account at all costs.

• Install Ubuntu 8.04 (Hardy Heron) from Ubuntu Download Page.

• Recommended Software Selection:
  • OpenSSH Server (for remote system management)
  • LAMP Server (for Apache2 web server, MySQL 5 relational database server)

• Reboot – you should now have a functional GNU/Linux server!

If you installed Ubuntu Server likely you are now being greeted with a command line prompt.

* Starting web server apache2                                    [ OK ]
* Running local boot scripts (/etc/rc.local)                     [ OK ]

Ubuntu 8.04.01 YOURSERVERNAME tty1

YOURSERVERNAME login:

If you installed from the Ubuntu Desktop CD you are likely booted into the graphical desktop. This setup guide is based entirely on console (terminal) access – so if you are running the desktop build of Ubuntu sign in as the user you created at install time, select Applications → Accessories → Terminal to open the terminal prompt.

The first step in setting up any server is to simply upgrade the system to the most current packages for security purposes.

$ sudo aptitude update && sudo aptitude full-upgrade

This should update most non-system critical packages (you may notice it will hold back installing Kernel updates).

Add an entry to apt to support the IndexData repository:

$ sudo nano /etc/apt/sources.list.d/indexdata.list

Type the following into the file:

# IndexData Repository
deb http://ftp.indexdata.dk/pub/ubuntu/ hardy main

You will also need the Ubuntu backports repository:

$ sudo nano /etc/apt/sources.list.d/backports.list

Type the following into the file

# Backports Repository
deb http://www.backports.org/debian/ etch-backports main

Save the document and quit. (Control+X)

IndexData packages are signed with a key you can install as follows:

$ cd ~
$ wget http://ftp.indexdata.dk/debian/indexdata.asc
$ sudo apt-key add indexdata.asc

Backports packages are signed with a key you can install as follows:

$ sudo aptitude update
$ sudo aptitude install debian-backports-keyring

Ubuntu 8.04 ships with support for UTF-8 enabled in Apache 2 and the console by default. If you wish to have a fully UNICODE compliant system you will need to enable UTF-8 support as the default in MySQL 5 as well.

(You may refer to this document – but it is generic to linux in general Please read over this document carefully)

(If you did not installed one of Ubuntu's desktop editions rather than the server edition you won't have apache2 or mysql-server installed yet. Use sudo aptitude install mysql-server apache2 install these first.) [Perhaps this encoding section should be moved down after the software installation sections?]

To set MySQL 5 to use UTF-8 do the following:

$ sudo nano /etc/mysql/my.cnf

Press control+w, type [mysqld], and you should be brought to this section:

[mysqld]
# 
# * Basic Settings
#

Under the basic settings section (The pound (#) signs denote a 'comment', or an unused configuration value) add:

# UTF-8 Defaults for Koha (added DATE by YOURNAME)
init-connect='SET NAMES utf8'
character-set-server=utf8
collation-server=utf8_general_ci

You should end up with:

[mysqld]
# 
# * Basic Settings
#

# UTF-8 Defaults for Koha (added DATE by YOURNAME)
init-connect='SET NAMES utf8'
character-set-server=utf8
collation-server=utf8_general_ci

Press control+x, say YES to save, and call it (the default) my.cnf.

Restart MySQL:

$ sudo /etc/init.d/mysql restart

Yaz is a z39.50 toolkit from IndexData. Zebra is a high-performance, general-purpose structured text indexing and retrieval engine.

You may not need Zebra, but you definitely need Yaz. Install them both regardless.

• Install libssl0.9.7 ( Needed For Yaz ). Hardy has libssl0.9.8, but yaz won't install with that one. We need to download the older version and install it by hand. (2.1mb).

wget http://mirrors.kernel.org/ubuntu/pool/universe/o/openssl097/libssl0.9.7_0.9.7g-5ubuntu1.1_i386.deb
sudo dpkg -i libssl0.9.7_0.9.7g-5ubuntu1.1_i386.deb

• Install Yaz, Zebra, and the Zebra documentation.

$ sudo aptitude install yaz idzebra idzebra-doc

At this point you should have Yaz, IDZegra, Apache and MySQL installed. If for some reason you are missing Apache and Mysql (php5 is nice to have for PHPMyAdmin):

$ sudo aptitude install \
    apache2-mpm-prefork apache2 apache2-utils apache2.2-common libapache2-mod-php5 \
    mysql-server php5-mysql

Also install some development software and tools that CPAN enjoys using:

$ sudo aptitude install \
    gzip tar unzip make lynx wget gcc daemon \
    libgpg-error-dev libgcrypt-dev libgdbm-dev libxml2-dev libyaz3-dev libgd2-xpm-dev

This is where your hands are going to start getting messy with installing the supporting Perl libraries for Koha. As Koha changes, you may need to vary this step slightly. The basic process is:

• Run configure
• Run make
• If any perl modules are missing; install them.
• We want to install as many Perl modules from apt as possible to help ease maintainability. The following was borrowed from the Required libraries entry.

$ sudo aptitude install \
    liblingua-stem-perl libxml-sax-machines-perl libmarc-record-perl libcgi-session-perl \
    libdate-pcalc-perl libdate-ical-perl libdate-manip-perl liblist-moreutils-perl \
    libmarc-charset-perl libmarc-xml-perl libnet-ldap-server-perl libpdf-report-perl \
    libpdf-reuse-barcode-perl libxml-csv-perl libtext-csv-perl libtext-iconv-perl \
    libxml-dumper-perl libxml-libxml-common-perl libxml-filter-xslt-perl \
    libxml-rsslite-perl libxml-simple-perl libyaml-syck-perl libxml-rss-perl \
    libschedule-at-perl libhtml-template-pro-perl libhtml-scrubber-perl \
    libmarc-crosswalk-dublincore-perl libdate-calc-perl \
    libclass-factory-perl libdata-ical-perl libmodule-pluggable-perl libyaml-perl     

This will install most of what Koha needs, however there are a few outdated packages and a couple that are missing.

$ sudo perl -MCPAN \
    -e 'install Time::Piece;' \
    -e 'install Email::Date;' \
    -e 'install Mail::Sendmail;' \
    -e 'install Text::Iconv;' \
    -e 'install Biblio::EndnoteStyle;' \
    -e 'install Algorithm::CheckDigits;' \
    -e 'install SMS::Send;' \
    -e 'install MIME::Lite;' \
    -e 'install Class::Factory::Util;' \
    -e 'install HTML::Template::Pro;' \
    -e 'install Net::Z3950;' \
    -e 'install Net::Z3950::ZOOM;' \
    -e 'install POE;' \
    -e 'install Text::CSV;' \
    -e 'install Text::CSV_XS;' \
    -e 'install MARC::File::XML;' \
    -e 'install Unix::Syslog;' \
    -e 'install GD;' \
    -e 'install HTTP::OAI;' \
    -e 'install JSON;' \
    -e 'install IPC::Cmd;' \
    -e 'install Digest::SHA;'

If the above code for installation of old package fail. Try installing each package independently.

sudo perl -e shell -MCPAN

for each package execute as in the following example.

install Time::Piece

Unix allows applications to be run under certain accounts to keep things segmented and more secure. We will now create an unprivilaged (non-root, non-administrative) Koha user account that will run all of the Koha operations. This automatically creates a koha group as well.

$ sudo adduser --gecos "Koha server" koha

Which will look something like this:

Adding user `koha' ...
Adding new group `koha' (1001) ...
Adding new user `koha' (1001) with group `koha' ...
Creating home directory `/home/koha' ...
Copying files from `/etc/skel' ...
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully

If you wish to use another password, or username than the default 'kohaadmin' and 'katikoan', change them in the following entries, as well as when you run perl Makefile.PL below. Please seriously consider changing them

$ sudo mysqladmin -uroot create koha -p 
$ sudo echo "grant all on koha.* to 'kohaadmin'@'localhost' identified by 'katikoan';" | mysql -uroot -p
$ sudo mysqladmin -uroot -p flush-privileges

Most people will want to use a standard release tarball from the Koha website.

• Download Koha from http://download.koha.org

$ sudo mkdir /build
$ cd /build
$ sudo wget http://download.koha.org/koha-3.00.02.tar.gz
$ sudo tar -xzvf koha-3.00.02.tar.gz
$ cd koha-3.00.02

$ perl Makefile.PL

Note: Make sure to answer the questions to match your environment. In most cases the defaults are fine, but make sure the passwords and user names match what you used earlier if you didn't use the defaults. Also, it is recommended that you use “dom” for the Authority Indexing Mode if you are using Zebra and don't have a reason to use the older grs1 option.

$ make
$ make test

Note: You may receive some errors during the make test complaining about an “Illegal Date” … they can safely be ignored.

$ sudo make install
$ (cd /etc/apache2/sites-available/ && sudo cp -s ../../koha/koha-httpd.conf ./koha)
$ sudo a2enmod rewrite && sudo a2ensite koha
$ sudo /etc/init.d/apache2 reload
$ sudo mkdir -p /var/lock/koha/zebradb/biblios /var/lock/koha/zebradb/authorities
$ sudo -u koha zebrasrv -f /etc/koha/koha-conf.xml &

• Open port 8080 in Apache
  • Edit /etc/apache2/ports.conf and add the line:

Listen 8080

• Restart Apache by executing the command:

$ sudo apache2ctl restart

• Browse to http://servername:8080/ and answer the questions.
• Note: If when you go to http://servername:8080/ all you see is the words “It works!” or similar, the <VirtualHost> lines in your koha-httpd.conf (by default in /etc/koha/koha-httpd.conf) may need to be edited to match your hostname.

If you decided to use Zebra Indexing, you will need to configure and start Zebra. It's recommended that you daemonize the Zebra process and add it to your startup profile. For a non-production test/development installation, running Zebra from the command line can be useful. Pick from the two available options below, or roll your own

Note: it's also recommended that you create a Koha system user, which you will have specified during the install process. Alternatively, Zebra can be configured to run as the root user.

Option 1: run the Zebra processes from the command line:

Zebra Server:

$ sudo -u ${KOHA_USER} zebrasrv -f /etc/koha/koha-conf.xml

Note that the path to koha-conf.xml may be different depending on your installation choices. Replace ${KOHA_USER} with the name you are running Koha under (typically this is koha). 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 -u ${KOHA_USER} ${SCRIPT_DIR}/zebraqueue_daemon.pl

Note: ${SCRIPT_DIR} is /usr/share/koha/bin by default in a standard install

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 8 chkconfig 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 8 chkconfig on other distros

$ sudo /etc/init.d/koha-zebraqueue-daemon start

In order to find items using the Zebra interface, you will have to schedule indexing. If you bulk imported bibliographic records, you will want to run a “Fast Index” first. This is done by entering the following command:

$ perl -I /usr/share/koha/lib /usr/share/koha/bin/migration_tools/rebuild_zebra.pl -v -b -w

The previous command will create the initial indexes, but new records will not be indexed until the rebuild_zebra.pl command is run again. You should set this up to run as a cron job every few minutes.

/usr/share/koha/bin/cronjobs/crontab.example has an example crontab file. Besides the zebra cron entries, it also has examples for other tasks. You probably do not want to enable the other tasks until they have been tested with your configuration and you know what they are doing. My crontab looks like this:

# m h  dom mon dow   command
PERL5LIB=/usr/share/koha/lib/
KOHA_CONF=/etc/koha/koha-conf.xml

## rebuild zebra
*/5 * * * * KOHA_CONF=/etc/koha/koha-conf.xml PERL5LIB=/usr/share/koha/lib/ /usr/share/koha/bin/migration_tools/rebuild_zebra.pl -b -a -z >/dev/null

The */5 in the above example tells zebra to reindex every five minutes. You can change this to another number to match your needs. The crontab.example uses */10 to do it every ten minutes.

To create a crontab, as user koha, do the following:

$ crontab -e

And then edit the file. By default ubuntu uses the nano editor, you can change it by running:

$ sudo update-alternatives --config editor

After creating the crontab, add a few bibliographic records and then wait a few minutes and check to see if they have been indexed.