Koha 3.0 on Debian Lenny

WARNING! This page is obsolete. This page is no longer correct and exists for historical reasons only. Please see Installation Documentation for current information

Prolegomena

The following installation instructions apply for both, debian lenny 32 and 64 bit (amd64).

Based on the installation instruction included in the official koha installation package, the following step by step instruction is enriched by necessary additional steps and details to get Koha compiled and installed without errors. In contrary to other Koha installation manuals from the web the objective here is to get a secure productive koha server 1. with a fully functional koha installation 2. on top of a minimal text based debian including only necessary debian services and packages 3. without a graphical user interface on the server to prevent the need of server rebooting and outage times

Installation Guide

All commands are performed as a system user with sudo privileges, it is not advisable by running the commands directly as root.

1. Prepare System and Install Dependencies

1.1 Install Debian Lenny via Businesscard or Netinstall CD

See http://www.debian.org/releases/lenny/debian-installer/ In the installation process select to add a network mirror and select one next to your servers location from here:

   http://www.debian.org/mirror/list

In the first field where you have to enter the server names path write exactly what's written here. And in the secondary field it's in most cases

   /debian/

1.3 Set up Indexdata apt sources for Yaz and Zebra packages

Edit your /etc/apt/sources.list file and add the following:

   # Index Data sources for Yaz and Zebra
   deb http://ftp.indexdata.dk/debian lenny main
   deb-src http://ftp.indexdata.dk/debian lenny main

The Index Data packages are signed with a key you can install as follows:

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

1.4 Get Koha from http://download.koha-community.org

Find the latest Koha stable version on http://koha-community.org/download-koha/ and get it:

   $ wget http://download.koha-community.org/koha-3.00.06.tar.gz
   $ tar xvfz koha-3.00.06.tar.gz
   $ cd koha-3.00.06

If you want to have koha installed with additional languages other than english download the koha-3.00.06-all-translations.tar.gz package. But this will add numerous languages and might reduce the server performance notably.

Finishing the installation of Koha from the normal (non all translations) package you can install at any time additional languages other than english as described her: Installation of additional languages for OPAC and INTRANET staff client.

1.5 Install additional Debian dependencies

IMPORTANT: You should only use CPAN for Perl dependencies which are NOT

           available from the package maintainer. You have been warned!

Using the debian-lenny.packages file included in the Koha source tree, update first your package index files fromt the repository sources and upgrade to the newest versions of installed packages:

   $ sudo apt-get update
   $ sudo apt-get upgrade

Remove duplicated and multiplicated lines and add the following lines - here with the editor nano to the file ".../install_misc/debian-lenny.packages":

   $ sudo nano -w install_misc/debian-lenny.packages

Additional lines to add:

   unzip	install
   ilbdbd-mysql	install

Optional lines to add:

   ssh	   install

If you want to ssh to your server.

Then run the following:

   $ sudo dpkg --set-selections < install_misc/debian-lenny.packages

Now start dselect:

   $ sudo apt-get install dselect
   $ sudo dselect

Choose [I]nstall and accept packages to be installed (hit return)

(may take a while)

Choose [C]onfigure, [R]emove and [Q]uit until dselect has completed.

1.6 Install Perl dependencies that aren't packaged into Debian Lenny sources

   $ sudo cpan

If you are running cpan for the first time, it will request you to configure it. Simply leave the defaults that cpan suggests.

   $ cpan> o conf commit

This will commit the configurations you just made

   $ cpan> quit

Run the following command:

   $ sudo cpan Algorithm::CheckDigits SMS::Send HTTP::OAI Text::CSV::Encoded

Note: you may need to run CPAN initialization if you've not run cpan before:

   $ sudo perl /etc/perl/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]

When the configuration is completed CPAN will install the Perl modules.

1.7 Configure UTF-8 encoding support in Apache:

   $sudo nano -w /etc/apache/apache2.conf

Add following three lines at the end of the file in apache2.conf and save and exit

   #UTF8 support
   AddDefaultCharset UTF-8
   AddCharset UTF-8 .utf8
   
   # server name
   #
   # If you have enter the proper host name of your computer here 
   # from /etc/hostname instead of “localhost”
   ServerName localhost

Open the ports.conf file and below Listen 80 add following line:

   $ sudo nano -w /etc/apache2/ports.conf

   Listen 8080

1.8 Set UTF-8 Encoding in MySQL:

Open the my.cnf file and add in [mysqld] and [client] the following lines:

   $ sudo nano -w /etc/mysql/my.cnf

   # UTF-8 Defaults for Koha
   [mysqld]
   default-character-set=utf8
   default-collation=utf8_general_ci
   character-set-server=utf8
   collation-server=utf8_general_ci
   init-connect='SET NAMES utf8'

   [client]
   default-character-set=utf8

   $ sudo /etc/init.d/mysql restart

2. Configuration of dependencies

2.1 Add koha mysql database user:

The kohadatabaseuser's name will be the login user name on the intranet / staff client user interface of koha.

   $ sudo adduser <kohadatabaseuser>

2.2 Update root MySQL password (if dselect didn't do it for you already)

   $ sudo mysqladmin password <password>

2.3 Create the Koha database

   Create the database and user with associated privileges:
   $ mysqladmin -uroot -pmysqlroot create kohadatabaseuser
   $ mysql -uroot -p
   
   mysql>create database <kohadatabasename>;
   mysql> grant all on <kohadatabasename>.* to '<kohadatabaseuser>'@'localhost' identified by '<mysql-password-for-kohadatabaseuser>'
   Query OK, 0 rows affected (0.00 sec)

   Note: For security reasons you might chose in mysql a different password for the kohadatabaseuser. Different from its linux login password  

   mysql> flush privileges;
   Query OK, 0 rows affected (0.00 sec)

   mysql> quit

2.3 Test your SAX Parser and correct where necessary

You must be sure you're using the XML::LibXML SAX parser, not Expat or PurePerl, both of which have outstanding bugs with pre-composed characters. You can test your SAX parser by running:

   $ cd koha-3.00.06
   $ misc/sax_parser_print.pl

   You should see something like::

   XML::LibXML::SAX::Parser=HASH(0x81fe220)

   If you're using PurePerl or Expat, you'll need to edit your
   ini file, typically located at:

   /etc/perl/XML/SAX/ParserDetails.ini

   move these lines to the bottom of the file:

   [XML::LibXML::SAX::Parser]
   http://xml.org/sax/features/namespaces = 1

3. Run the Koha installer

   $ perl Makefile.PL
   ( answer questions )

If you see error messages like these ...

   [Thu Jun  3 22:58:33 2010] Makefile.PL: Warning: prerequisite GD 2.39 not found.
   [Thu Jun  3 22:58:33 2010] Makefile.PL: Warning: prerequisite GD::Barcode::UPCE 1.1 not found.
   [Thu Jun  3 22:58:33 2010] Makefile.PL: Warning: prerequisite IPC::Cmd 0.46 not found. We have 0.401.
   [Thu Jun  3 22:58:35 2010] Makefile.PL: Warning: prerequisite PDF::Reuse::Barcode 0.05 not found.

... you have to install additionally from cpan the appropriate versions:

   $ sudo cpan GD::Barcode::UPCE GD IPC::Cmd PDF::Reuse::Barcode

Additionally it might be necessary to install this package:

   $ sudo wget http://www.libgd.org/releases/gd-2.0.35.tar.gz

   $ tar -xzvf tar -xzvf gd-2.0.35.tar.gz
   $ cd gd-2.0.35
   $ ./configure
   $ make
   $ sudo make install

Now it should be possible to compile Koha without errors (If you ran the above package remember to change back to the koha-3.00.06 directory):

   $ make
   $ make test
   $ sudo make install

4. Steps after the installation:

4.1 In order to use Koha's command-line batch jobs, you should set the following environment variables:

export KOHA_CONF=/etc/koha/koha-conf.xml export PERL5LIB=/usr/share/koha/lib

4.2 Configure and start Apache

   $ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha

Note that the path to koha-httpd.conf may be different depending on your installation choices.

Add the following lines to /etc/apache2/ports.conf:

   Listen 80
   Listen 8080

Run the following commands:

   $ sudo /usr/sbin/a2enmod rewrite
   $ sudo /usr/sbin/a2ensite koha
   $ sudo /usr/sbin/apache2ctl restart

Note: you may still see the usual Apache default site if your VirtualHost configuration isn't correct. The command "sudo /usr/sbin/a2dissite default" may be a quick fix, but may have side-effects. See the Apache HTTPD manual section on virtual hosts for full instructions.

5. Configure and start Zebra

Note: 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)

   Note: 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} misc/bin/zebraqueue_daemon.pl

   Note: if you are running in this mode, you may wish to defer starting the
   zebraqueue until you've run the web installer (see below).

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

   $ sudo ${SCRIPT_DIR}/koha-zebraqueue-ctl.sh start

6. Run the Web Installer, populate the database, initial configuration of settings

   Point your browser to http://<servername>:8080/

   It should redirect you to the Web Installer where you can continue the setup.
   You can install the sample data for libraries, patrons, etc. via the Web Installer

7. What next?

   Once the installer has completed, you can import and index MARC records from the
   command line thusly (Note: you can also use the 'Stage MARC records for import' from
   the Tools area of Koha's Staff Client to import a batch of MARC records):

   $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml
     (note: use the correct path to your koha-conf.xml)

7.1 Import:

   Bibliographic data in MARC21 format
   $ misc/migration-tools/bulkmarcimport.pl -file /path/to/marc.iso2709
   Authority data in MARC21 format
       $ misc/migration-tools/bulkauthimport.pl -file /path/to/auth.iso2709

7.2 Fast Index:

   $ misc/migration-tools/rebuild_zebra.pl -b -w

   Once the indexing has completed, you will be able to search for records in your
   system. NOTE: if you don't run the Fast Index utility, and you have the index
       updates scheduled as per 7.3 the indexing process will happen in the background,
       but it will be orders of magnitude slower.

7.3 Schedule regular index updates

   run rebuild_zebra.pl -b -a -z as a regular cron job,
   check misc/cronjobs/crontab.example for usage examples

7.4 To enable public Z39.50/SRU servers, you'll need to edit your koha-conf.xml and

   change the <listen> options to listen on a TCP port; then restart the zebra daemon.

Upgrade

If you are upgrading from a previous installation of Koha 3, you can use the following:

perl Makefile.PL --prev-install-log /path/to/koha-install-log
make
make test
sudo make upgrade

Uninstall Instructions

1) Stop Services:

  $ sudo a2dissite koha
  $ sudo rm /etc/apache2/sites-available/koha
  $ sudo apache2ctl restart

  $ sudo update-rc.d koha-zebra-daemon remove
  $ sudo rm /etc/init.d/koha-zebra-daemon

2) Remove Database and Indexes

  # MySQL
  $ mysql -u<kohauser> -p<kohapassword>
  > drop database koha;

  # Zebra Indexes
  $ zebraidx -c <prefix>/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
  $ zebraidx -c <prefix>/etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init

3) Remove Koha Install Directories and Configuration Files

  Don't forget about any crontab entries

WARNING! This page is obsolete. This page is no longer correct and exists for historical reasons only.