From 899cca556219e4c82c1295fbfbec50abaaece5b9 Mon Sep 17 00:00:00 2001 From: Chris Nighswonger Date: Tue, 23 Jun 2009 13:18:04 -0400 Subject: [PATCH] Adding installation documentation for Ubuntu Signed-off-by: Galen Charlton --- INSTALL.ubuntu | 410 +++++++++++++++++++++++++++++++++++ install_misc/ubuntu.packages | 90 ++++++++ 2 files changed, 500 insertions(+) create mode 100644 INSTALL.ubuntu create mode 100644 install_misc/ubuntu.packages diff --git a/INSTALL.ubuntu b/INSTALL.ubuntu new file mode 100644 index 0000000000..69e7b6ac3b --- /dev/null +++ b/INSTALL.ubuntu @@ -0,0 +1,410 @@ +============================= +Installation Guide for Installing Koha on Ubuntu Jaunty (9.04) with MySQL 5 +============================= + +Copyright (C) 2007, 2008 LibLime (http://liblime.com) + +Original author: Joshua Ferraro (jmf AT liblime DOT com) +Modified for Ubuntu by: Chris Nighswonger (cnighswonger AT foundations DOT edu) + +Feedback/bug reports: Koha Developer's List: +http://lists.koha.org/mailman/listinfo/koha-devel + +This document last modified: 22 June 2009 + +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 Ubuntu Jaunty via CD + +See http://www.ubuntu.com/getubuntu/download + +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 + +You can verify your system locale by typing the following command: + + $ locale + +IMPORTANT: You _MUST_ follow all the steps outlined there for + Apache2, MySQL 5, etc. BEFORE you install Koha. + +1.3 Install the Yaz and Zebra packages + +Run the following command to update your system: + + $ sudo apt-get update + $ sudo apt-get install yaz idzebra-2.0 idzebra-2.0-doc + +1.4 Get Koha + +1.4.1 Option A: Download Koha via Git (optional) + + $ sudo apt-get install git-core git-email + $ git clone git://git.koha.org/pub/scm/koha.git kohaclone + $ cd kohaclone + $ git checkout -b myinstall origin + +Note: for more information about Git, please see the Koha Git Usage Guide: + + http://wiki.koha.org/doku.php?id=en:development:git_usage + +1.4.2 Option B: Download Koha from http://download.koha.org + + $ wget http://download.koha.org/koha-3.00.02.tar.gz + ( Note: use the latest stable version) + +1.5 Install additional Ubuntu dependencies + +IMPORTANT: You should only use CPAN for Perl dependencies which are NOT + available from the package maintainer. You have been warned! + +Using the ubuntu.packages file included in the Koha source tree, +run the following: + + $ sudo dpkg --set-selections < install_misc/ubuntu.packages + +Now start dselect (you may need to '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 Ubuntu Jaunty +sources + +Run the following command: + + $ sudo cpan MARC::Crosswalk::DublinCore GD GD::Barcode::UPCE Email::Date \ + HTML::Scrubber Algorithm::CheckDigits::M43_001 Biblio::EndnoteStyle + +Note: you may need to run CPAN initialization if you've not run cpan +before: + + /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. + +2. Configuration of dependencies + +2.1 Update root MySQL password (if dselect didn't do it for you already) + + $ sudo mysqladmin password + +2.2 Create the Koha database + + Create the database and user with associated privileges: + + $ mysqladmin -uroot -p create + $ mysql -uroot -p + + Welcome to the MySQL monitor. Commands end with ; or \g. + Your MySQL connection id is 22 + Server version: 5.0.32-Debian_7etch3-log Debian etch distribution + + Type 'help;' or '\h' for help. Type '\c' to clear the buffer. + + mysql> grant all on .* to ''@'localhost' identified by ''; + Query OK, 0 rows affected (0.00 sec) + + 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 + $ 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 + +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 +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: + + $ mysql -uroot -p + + Create the database and user with associated privileges: + + Welcome to the MySQL monitor. Commands end with ; or \g. + Your MySQL connection id is 22 + Server version: 5.0.32-Debian_7etch3-log Debian etch distribution + + Type 'help;' or '\h' for help. Type '\c' to clear the buffer. + + mysql> create database test; + Query OK, 1 row affected (0.00 sec) + + mysql> grant all on test.* to 'test'@'localhost' identified by 'test'; + Query OK, 0 rows affected (0.00 sec) + (test database, user, and password can be different if need be) + + mysql> flush privileges; + Query OK, 0 rows affected (0.00 sec) + + mysql> quit + +Next install DBD::mysql: + + $ sudo cpan + + cpan> o conf makepl_arg + (get current value of this CPAN parameter) + + cpan> o conf makepl_arg "--testdb=test --testuser=test --testpass=test" + + cpan> install DBD::mysql + + cpan> o conf makepl_arg '' + + OR + + cpan> o conf makepl_arg '' + + (restore this setting so as to not interfere with future CPAN installs). + + +Finally, remove the test database: + + $ mysql -uroot -p + + mysql> drop database test; + Query OK, 1 row affected (0.00 sec) + + mysql> exit + Bye + +3. Run the Koha installer + + $ perl Makefile.PL + ( answer questions ) + $ make + $ make test + $ sudo make install + +4. 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 + +If not running named virtual hosts (The default koha installation does not use named virtual hosts.), comment out the following line: + + NameVirtualHost *:80 + +Run the following commands: + + $ sudo a2enmod rewrite + $ 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 :-) + +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. + +To add a user do: + + $ sudo adduser koha + + +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://: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 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 -p + > drop database koha; + + # Zebra Indexes + $ zebraidx -c /etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init + $ zebraidx -c /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 +============================================== +- Ubuntu Jaunty Jackalope 9.04 + +Installer Bug reports +===================== +Please log any installer bug reports at http://bugs.koha.org + +Other Notes +===================== +This file is part of Koha + +Koha is free software; you can redistribute it and/or modify it under the +terms of the GNU General Public License as published by the Free Software +Foundation; either version 2 of the License, or (at your option) any later +version. + +Koha is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +A PARTICULAR PURPOSE. See the GNU General Public License for more details. +You should have received a copy of the GNU General Public License along with +Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place, +Suite 330, Boston, MA 02111-1307 USA diff --git a/install_misc/ubuntu.packages b/install_misc/ubuntu.packages new file mode 100644 index 0000000000..818358ad02 --- /dev/null +++ b/install_misc/ubuntu.packages @@ -0,0 +1,90 @@ +at install +apache2 install +cvs install +daemon install +libgcrypt11 install +libgcrypt11-dev install +make install +gcc install +gettext install +mysql-server install +libcgi-session-perl install +libclass-factory-util-perl install +libdate-calc-perl install +libdate-manip-perl install +libdate-ical-perl install +libdatetime-format-mail-perl install +libimage-magick-perl install +libmail-sendmail-perl install +liblingua-ispell-perl install +liblingua-stem-perl install +libdbd-mysql-perl install +idzebra-2.0 install +idzebra-2.0-common install +idzebra-2.0-doc install +idzebra-2.0-utils install +libclass-factory-util-perl install +libdatetime-format-strptime-perl install +libdatetime-format-w3cdtf-perl install +libdatetime-locale-perl install +libdatetime-perl install +liblist-moreutils-perl install +libdatetime-timezone-perl install +libdbi-perl install +libidzebra-2.0 install +libidzebra-2.0-dev install +libidzebra-2.0-mod-alvis install +libidzebra-2.0-mod-grs-marc install +libidzebra-2.0-mod-grs-regx install +libidzebra-2.0-mod-grs-xml install +libidzebra-2.0-mod-text install +libidzebra-2.0-modules install +libmysqlclient15-dev install +libnet-ldap-perl install +liblist-moreutils-perl install +liblocale-gettext-perl install +liblocale-po-perl install +libpdf-api2-perl install +libmime-lite-perl install +libpoe-perl install +libtext-csv-perl install +libtext-charwidth-perl install +libtext-iconv-perl install +libtext-wrapi18n-perl install +libtime-duration-perl install +libtime-format-perl install +libtimedate-perl install +libunix-syslog-perl install +libxml-dom-perl install +libxml-dumper-perl install +libxml-namespacesupport-perl install +libxml-parser-perl install +libxml-perl install +libxml-simple-perl install +libxml-regexp-perl install +libxml-xslt-perl install +libxml-libxml-perl install +libxml-libxslt-perl install +libxml2 install +libxml2-dev install +libxml2-utils install +libxslt1-dev install +libxslt1.1 install +libyaml-syck-perl install +libyaz install +libyaz-dev install +yaz install +yaz-doc install +libcgi-session-serialize-yaml-perl install +libdata-ical-perl install +libhtml-template-pro-perl install +libmarc-charset-perl install +bmarc-record-perl install +libmarc-xml-perl install +libnet-z3950-zoom-perl install +libpdf-reuse-perl install +libpdf-reuse-barcode-perl install +libsms-send-perl install +libschedule-at-perl install +libxml-rss-perl install +libmime-lite-perl install -- 2.39.5