Installation Guide for Installing Koha on Debian Etch with MySQL 5
=============================
-Copyright (C) 2007, LibLime
+Copyright (C) 2007, 2008 LibLime (http://liblime.com)
Maintainer: Joshua Ferraro (jmf AT liblime DOT com)
-Feedback/bug reports: jmf AT liblime DOT com
-This document last modified: 29 December 2007
+
+Feedback/bug reports: Koha Developer's List:
+http://lists.koha.org/mailman/listinfo/koha-devel
+
+This document last modified: 30 April 2008
Installation Instructions
=============================
All commands can be performed as a system user with sudo privileges,
as indicated or by running the command directly as root.
+1. Prepare System and Install Dependencies
+
+1.1 Install Debian Etch via Businesscard CD
+
+See http://www.debian.org/releases/etch/debian-installer/
+
+WARNING: use Perl 5.8 (a library Koha depends on,
+MARC::File::XML may not work with Perl 5.10, see:
+http://bugs.koha.org/cgi-bin/bugzilla/show_bug.cgi?id=2309),
+
+1.2 Set up your locale
+
Your locale should be set to UTF-8, as should Apache2 and MySQL 5.
This step is VERY IMPORTANT for a UNICODE compliant system. Please
read over the following document carefully:
http://wiki.koha.org/doku.php?id=encodingscratchpad
-1. Prepare System and Install Dependencies
-
-1.1 Install Debian Etch via Businesscard CD
-
-See http://www.debian.org/devel/debian-installer/
+IMPORTANT: You _MUST_ follow all the steps outlined there for
+ Apache2, MySQL 5, etc. BEFORE you install Koha.
-1.2 Set up apt sources for Git, Yaz and Zebra packages
+1.3 Set up apt sources for Git, Yaz and Zebra packages
Edit your /etc/apt/sources.list file and add the following:
Backports packages are signed with a key you can install as follows:
+ $ sudo apt-get update
$ sudo apt-get install debian-backports-keyring
The Index Data packages are signed with a key you can install as follows:
$ sudo apt-get -t etch-backports install git-core git-email
$ sudo apt-get install yaz idzebra-2.0 idzebra-2.0-doc
-1.3 Get Koha
+1.4 Get Koha
-1.3.1 Option A: Download Koha via Git (optional)
+1.4.1 Option A: Download Koha via Git (optional)
$ git clone git://git.koha.org/pub/scm/koha.git kohaclone
$ cd kohaclone
http://wiki.koha.org/doku.php?id=en:development:git_usage
-1.3.2 Option B: Download Koha from koha.org
+1.4.2 Option B: Download Koha from http://download.koha.org
-1.4 Install additional Debian dependencies
+ $ wget http://download.koha.org/koha-3.00.00-beta.tar.gz
+ ( Note: use the latest stable version)
-IMPORTANT: You should only use CPAN for Perl dependencies which are NOT available from the package maintainer.
- You have been warned!
+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.packages file included in the Koha source tree,
run the following:
Choose [C]onfigure, [R]emove and [Q]uit until dselect has completed.
-1.5 Install Perl dependencies that aren't packaged into Debian Etch
+1.6 Install Perl dependencies that aren't packaged into Debian Etch
sources
Run the following command:
$ sudo cpan MARC::Record Class::Accessor MARC::Charset MARC::File::XML \
Net::Z3950::ZOOM HTML::Template::Pro MARC::Crosswalk::DublinCore \
PDF::Reuse PDF::Reuse::Barcode Data::ICal GD::Barcode::UPCE \
- XML::RSS Algorithm::CheckDigits::M43_001 Biblio::EndnoteStyle POE Schedule::At
+ XML::RSS Algorithm::CheckDigits::M43_001 Biblio::EndnoteStyle POE \
+ Schedule::At DBD::SQLite GD SMS::Send HTTP::OAI IPC::Cmd Text::CSV::Encoded
+
+
+ WARNINGS:
+ 1.6.1 A Perl library Koha depends on, MARC::File::XML may not work with Perl
+ 5.10, see: http://bugs.koha.org/cgi-bin/bugzilla/show_bug.cgi?id=2309),
-There is a known but benign error in the test case for Barcode::Code128,
-which is required by PDF::Reuse::Barcode. If this module is not installed,
-you can do a forced installation of Barcode::Code128.
+ 1.6.2 Recent versions of CGI::Session have caused some issues for users;
+ as of this release date, we suggest downloading the CGI::Session::Serialize::yaml
+ tarball direct from CPAN and install it directly rather than using the cpan command
+
+ 1.6.3 There is a known but benign error in the test case for Barcode::Code128,
+ which is required by PDF::Reuse::Barcode. If this module is not installed,
+ you can do a forced installation of Barcode::Code128.
Note: you may need to run CPAN initialization if you've not run cpan
before:
Create the database and user with associated privileges:
- $ mysqladmin -uroot -p<password> create database <kohadatabasename>
+ $ mysqladmin -uroot -p<password> create <kohadatabasename>
$ mysql -uroot -p<password>
Welcome to the MySQL monitor. Commands end with ; or \g.
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
$ misc/sax_parser_print.pl
You should see something like::
/etc/perl/XML/SAX/ParserDetails.ini
-2.4 Create test database in order to install DBD::mysql
+2.4 Install DBD::mysql Perl module
In order to handle UTF-8 correctly, Koha requires at least version 4.004
-of the DBD::mysql Perl module. However, Debian Etch has a stable package
+of the DBD::mysql Perl module. However, Debian Etch has a stable package
only for version 3.0008, so it is necessary to install the module from CPAN.
+DBD::mysql's test suite needs to use a MySQL 'test' DB which doesn't exist
+anymore. So there are two options to install DBD::mysql:
+
+ (1) install without test suite,
+ (2) install with test suite requiring a test MySQL DB creation.
+
+2.4.1 Install without test suite
+
+Force install DBD::mysql:
+
+ $ sudo cpan
+ cpan> force install DBD::mysql
+
+2.4.2 Create test database in order to install DBD::mysql
+
Because of DBD::mysql's test suite, it is necessary to temporarily create a
test database and user:
cpan> install DBD::mysql
cpan> o conf makepl_arg ''
- (clear this setting to not interface with future CPAN installs).
+
+ OR
+
+ cpan> o conf makepl_arg '<old setting>'
+
+ (restore this setting so as to not interfere with future CPAN installs).
Finally, remove the test database:
( answer questions )
$ make
$ make test
- $ sudo make install
+ $ sudo make install #If doing a -dev install, skip the sudo!
4. Configure and start Apache
$ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha
Add the following lines to /etc/apache2/ports.conf:
Listen 80
- Listen 8080
+ Listen 8080
+
+(Note: It may be productive to use different DNS entries and NamedVirtualHosts
+directives in Apache to separate the staff and OPAC clients, to eliminate a
+cross-client authentication nuisance, but it will work fine like this.)
Run the following commands:
$ sudo a2ensite koha
$ sudo apache2ctl restart
+Note: you may still see the usual Apache default site if your VirtualHost
+configuration isn't correct. The command "sudo 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 :-)
+Zebra from the command line can be useful. Otherwise you will want zebrasrv
+running when Apache/Koha is.
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
on the Zebra index; in development mode, you may wish to use your system
user.
- Zebraqueue Daemon:
+ Zebraqueue Daemon (not recommended -- use rebuild_zebra in crontab instead):
$ sudo -u ${KOHA_USER} misc/bin/zebraqueue_daemon.pl
Note: if you are running in this mode, you may wish to defer starting the
$ sudo ${SCRIPT_DIR}/koha-zebra-ctl.sh start
- Zebraqueue Daemon:
+ Zebraqueue Daemon (not recommended -- use rebuild_zebra in crontab instead):
$ 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 )
Point your browser to http://<servername>:8080/
- It should redirect you to the Web installer where you can continue the setup.
+ 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.0 Schedule crontab jobs
+ Do you want Koha to:
+ send mail?
+ automatically index added records?
+ generate overdue or advance notices?
+ mark items lost after they are long overdue?
+ assess fines?
+
+ All these and other regularly scheduled background tasks are handled by crontab.
+ You need to examine the example crontab file, edit a copy to your liking, and schedule it.
+
+ $ crontab -l # just check if you have any other jobs already scheduled
+ $ cp ./misc/cronjobs/crontab.example my_crontab
+ $ vi my_crontab # select jobs or adjust times.
+ $ # If you had already scheduled lines, add them at the bottom.
+ $ crontab my_crontab # This overwrites your scheduled jobs with the new ones.
+
+ If you want to check to confirm, you can run crontab -l again.
+
+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. Do not schedule rebuild_zebra AND run zebraqueue. Pick one or the other.
+ See 7.0 above.
+
+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
=============================
$ sudo apache2ctl restart
$ sudo update-rc.d koha-zebra-daemon remove
- $ sudo update-rc.d koha-zebraqueue-daemon remove
$ sudo rm /etc/init.d/koha-zebra-daemon
- $ sudo rm /etc/init.d/koha-zebraqueue-daemon
-2) Remove Koha Databases
+2) Remove Database and Indexes
# MySQL
$ mysql -u<kohauser> -p<kohapassword>
$ 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
Tested on the following operating environments
==============================================
projects / koha.git / blobdiff