Koha 3.0 on Debian Lenny

=== WARNING: Both Koha 3.0 and Debian Lenny are unsupported. There will be no updates for them. It is not recommended to use these versions for anything. Try this guide to installing Koha on Debian instead. ===
== 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
Category:Documentation
Category:Installation
Category:3.0
Category:Obsolete