================================================================= Installation Guide for Installing Koha on Ubuntu Precise Pangolin (12.04 LTS) with MySQL 5.5 ================================================================= Copyright (C) 2007, 2008 LibLime (http://liblime.com) Some parts copyright 2010 Chris Nighswonger Some parts copyright 2012 Tomas Cohen Arazi Some parts copyright 2012 Mark Tompsett Original author: Joshua Ferraro Modified for Ubuntu by: Chris Nighswonger (cnighswonger AT foundations DOT edu) More updates by: Tomas Cohen Arazi (tomascohen AT gmail DOT com) Mark Tompsett (mtompset AT hotmail DOT com) Feedback/bug reports: Koha Developer's List: http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel This document last modified: 24 July 2012 Installation Instructions ================================================================= Running commands can mostly be performed as a system user with sudo privileges, however some need to be run directly as root. 1. Prepare System and Install Dependencies 1.1 Install Ubuntu 12.04 LTS via CD/DVD/USB Download and install Ubuntu from the official site. - Server edition (command-line only) http://www.ubuntu.com/download/server - Desktop edition http://www.ubuntu.com/download/desktop To keep your Koha installation minimal and to free resources for running, the Server edition is recommended, though the Desktop edition will work as well. As Apache and MySQL will be installed in the instructions later, there is no need to select any packages during the installation of Ubuntu. 1.2 Add koha repository to your apt sources NOTE: This is not required for koha 3.6.7 under Ubuntu 12.04 if Zebra indexing (see step 5.2) is done via cron jobs. NOTE: 3.8.x is the recommended current stable release to use. There are currently three active repositories: oldstable, squeeze, and squeeze-dev. As of 2012-07-24, they represent 3.6.x, 3.8.x, and master respectively. This will change when 3.10.x is released. They will represent 3.8.x, 3.10.x, and master respectively. It is recommended to use squeeze at this time, as 3.8.x is the current stable release. Run these commands: $ echo "deb http://debian.koha-community.org/koha squeeze main" | sudo tee /etc/apt/sources.list.d/koha-community.list $ wget -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add - $ sudo apt-get update ; sudo apt-get upgrade 1.3 Install Apache2 and MySQL 5.5 Install the Apache2 server: $ sudo apt-get install apache2 If your MySQL server will be on your Koha server, or this instruction is confusing: $ sudo apt-get install mysql-server NOTE: You will be prompted to set your root password for MySQL. 1.4 Set up your locale Your locale should be set to UTF-8, as should Apache2 and MySQL 5.5. This step is VERY IMPORTANT for a UNICODE compliant system. You _MUST_ be sure to set this BEFORE you install Koha. 1.4.1 Ubuntu Locale Verify you have a UTF-8 locale in use: $ locale You will recognize if it is UTF-8 or not. Ubuntu 12.04 should not generally require any further steps. If it is not set to something UTF-8, use: $ locale -a You can select one (note that utf8 becomes UTF-8) and use: $ sudo update-locale LANG=en_US.UTF-8 You have to log out and back in to see locale change reflected in the locale command. Verify your system local by running the following command: $ locale 1.4.2 Apache2 and MySQL Locales Please read over the following document carefully for more information: http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Configuring_the_Character_Set 1.5 Get Koha There are two suggested ways to install Koha. If you will be participating in Koha's development, the Download from Git is the recommended way. If you will not be, then follow the Download from Tarball instructions. 1.5.1 Download via Git Install Git: $ sudo apt-get install git-core Download Koha: $ git clone git://git.koha-community.org/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-community.org/wiki/Version_Control_Using_Git 1.5.1 Download Koha released tarball You can get the sources from http://download.koha-community.org. Issuing the following command you can get the latest stable release (recommended): Download and Unpack Koha: $ wget http://download.koha-community.org/koha-latest.tar.gz $ tar xvf koha-latest.tar.gz Determine the version and change directory: $ ls koha-3.08.03 koha-lastest.tar.gz $ cd koha-3.08.03 1.6 Install additional Ubuntu dependencies Several Koha dependencies have been conveniently packaged and will be installed issuing the following commands: $ sudo apt-get install dselect $ sudo dpkg --set-selections < install_misc/ubuntu.packages $ sudo dselect Choose [I]nstall and accept packages to be installed and hit return. Be patient. This may take a long time. Choose [C]onfigure, [R]emove and [Q]uit until dselect has completed. 1.7 Install Perl dependencies that aren't packaged **************************************************************** IMPORTANT: You should only use CPAN for Perl dependencies which are NOT available from the package maintainer. You have been warned! **************************************************************** Run the test script to identify missing libraries $ perl koha_perl_deps.pl -m -u If there are any dependencies which are missing or need upgrading, first attempt aptitude searches: $ aptitude search libbusiness-isdn-perl Notice how the name transformed to 'lib' plus the lowercase library name using '-'s instead of '::'s plus '-perl'. This will generally help find what is missing. And then a simple apt-get install can be done: $ sudo apt-get install libbusiness-isdn-perl Do this for all the dependencies listed. Then re-run the command: $ perl koha_perl_deps.pl -m -u In general, the repositories on debian.koha-community.org should have any missing pieces. The list should be empty. If any are still listed, they can be installed using the 'cpan' command. If and only if you are unable to find any of the dependencies should you use the cpan command. For example: $ sudo cpan GD GD::Barcode::UPCE Algorithm::CheckDigits 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 passed on the command-line. For further explanation and reading see: http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Ubuntu_Packages_for_Perl_Dependencies 2. Configuration of dependencies 2.1 Update root MySQL password If during the installation of MySQL you were not prompted to set the MySQL password: $ sudo mysqladmin password 2.2 Create the Koha database Create the database and user with associated privileges. To do this, decide on the koha database name, the koha user name, and the koha user password. Substitute these into the following commands: $ mysql -u root -p Enter mysql root password: Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 42 Server version: 5.5.24-0ubuntu0.12.04.1 (Ubuntu) Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. mysql> CREATE DATABASE {kohadatabasename}; mysql> SHOW DATABASES; mysql> CREATE user '{kohauserbasename}'@'localhost' IDENTIFIED by '{kohauserpassword}'; mysql> GRANT ALL ON {kohadatabasename}.* TO '{kohausername}'@'localhost' IDENTIFIED BY '{kohauserpassword}'; mysql> USE mysql; mysql> SELECT host,user FROM user; mysql> DELETE FROM user WHERE user=''; mysql> SELECT host,user FROM user; mysql> FLUSH PRIVILEGES; mysql> QUIT For further explanation of these commands see: http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Create_MySQL_Database_and_Grant_Privileges 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. Test your SAX parser by running: $ ./misc/sax_parser_print.pl If your setup is wrong, the script will output something like: Koha wants something like: XML::LibXML::SAX::Parser=HASH(0x81fe220) You have: XML::SAX::Expat=HASH(0x1a94e88) Looks bad, check INSTALL.* documentation. It means you are using Expat (it could also say PurePerl). You'll need to edit your ini file, located at: /etc/perl/XML/SAX/ParserDetails.ini Move the entire section for '[XML::LibXML::SAX::Parser]' to the bottom of the ini file. Then run the script again. The output should look like this: $ misc/sax_parser_print.pl Koha wants something like: XML::LibXML::SAX::Parser=HASH(0x81fe220) You have: XML::LibXML::SAX::Parser=HASH(0x16dfee8) Looks good. For further details see: http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Test_to_make_sure_the_SAX_Parser_is_setup_correctly 3. Run the Koha installer Add a user for installing koha and running zebra: $ sudo adduser koha Build and install Koha: $ perl Makefile.PL ( answer questions ) $ make $ make test $ sudo make install 4. Configure and start Apache This will help make koha available to be a website: $ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha NOTE: the path to koha-httpd.conf may be different depending on your installation choices. Make sure you have this lines in /etc/apache2/ports.conf: Listen 80 Listen 8080 Add the missing one. The default installation of Koha does not use named virtual hosts. If you will not be running named virtual hosts, comment out the following line: NameVirtualHost *:80 Run the following commands: $ sudo a2enmod rewrite deflate $ 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 This process send responses to search requests sent by Koha or Z39.50/SRU/SRW clients. 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. 5.1 Zebra Search Server Set the zebra daemon to run on start: $ sudo ln -s /usr/share/koha/bin/koha-zebra-ctl.sh /etc/init.d/koha-zebra-daemon $ sudo update-rc.d koha-zebra-daemon defaults $ sudo /etc/init.d/koha-zebra-daemon start NOTE: change the path to koha-zebra-ctl.sh to match your setup if not using the default. 5.2 Zebra Indexer There are two ways to do this. ONLY DO ONE! DO NOT DO BOTH! Option 1: You can configure zebra-indexing as an background daemon, see http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra Option 2: Add an entry in Koha user crontab to scheduled added/updated/deleted records indexing by Zebra with this command: /misc/migration_tools/rebuild_zebra -z -b -a See check misc/cronjobs/crontab.example for usage examples. NOTE: This job should be setup under the kohauser (the default is 'koha'). 6. Run the Web Installer, populate the database, initial configuration of settings The hope is that your server is accessible via a nice browser somewhere. If not, install lynx to finish the web install on your Koha server: $ sudo apt-get install lynx Point your browser to http://:8080/ If you installed lynx, and are using defaults, it might be something like: $ lynx http://127.0.1.1: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. Install additional languages In your install directory you can run this commands to have your Koha setup translated to your language: Set your environment variables: $ export KOHA_CONF=/etc/koha/sites/koha/koha-conf.xml $ export PERL5LIB=/usr/share/koha/lib/ NOTE: the path to koha-conf.xml may be different depending on your installation choices. Run the translator script: $ cd /usr/share/koha/misc/translator $ perl translate install must be one of the included in the misc/translator/po directory. NOTE: You can add as many languages as you need. In order to use them you will have to enable them first in the 'I18N/L10N' section of the Koha preferences. 8. What next? NOTE: You can use the 'Stage MARC records for import' from the Tools area of Koha's Staff Client to import a batch of MARC records, rather than these instructions. Once the installer has completed, you can import and index MARC records from the command line thusly: $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml NOTE: use the correct path to your koha-conf.xml 8.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 8.2 Fast Index: NOTE: This script must be run as the kohauser otherwise permission errors and indexing problems will follow. (the default is 'koha' -- see step 3). $ misc/migration_tools/rebuild_zebra.pl -b -w Once the indexing has completed, you will be able to search for records in your system. 8.3 Public Z39.50/SRU server 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 running in another language other than english, please switch to english before doing the upgrade, the templating system has changed and the templates will need to be regenerated. Once you have upgraded, please regenerate your templates in your chosen languages. 1. Install new Perl dependencies If you are upgrading from a previous installation of Koha 3.x, you can use the following to identify new Perl dependencies: $ ./koha_perl_deps.pl -u -m Install any missing modules using the instructions on sections 1.6 and 1.7. 2. Upgrade Koha $ perl Makefile.PL --prev-install-log /path/to/koha-install-log $ make $ make test $ sudo make upgrade 3. Pre-3.4 upgrades Koha 3.4.x or later no longer stores items in biblio records so if you are upgrading from an older version as part of the upgrade you will need to do the following two steps, they can take a long time (several hours) to complete for large databases: $ misc/maintenance/remove_items_from_biblioitems.pl --run $ misc/migration_tools/rebuild_zebra.pl -b -r Uninstall Instructions ================================================================= 1. Stop Services: Firstly, remove the apache website: $ sudo a2dissite koha $ sudo rm /etc/apache2/sites-available/koha $ sudo apache2ctl restart Next, remove the koha-zebra-daemon: $ sudo update-rc.d koha-zebra-daemon remove $ sudo rm /etc/init.d/koha-zebra-daemon 2a. Remove Database: Remember the , need to be substituted on the following commands: $ mysql -u -p mysql> drop database ; 2b. Remove Indexes: To help determine what should be substituted with, run the following command: $ sudo find / -name "zebra-biblios.cfg" /etc/koha/zebradb/zebra-biblios.cfg /home/user/koha-3.08.03/etc/zebradb/zebra-biblios.cfg /home/user/koha-3.08.03/blib/ZEBRA_CONF_DIR/zebra-biblios.cfg There may be three copies, two of which will likely be in the user account that installed Koha. In this example, our is '/etc/koha'. Once you know the value of prefix, run these commands substituting in the correct value: $ zebraidx -c /zebradb/zebra-biblios.cfg -g iso2709 -d biblios init $ zebraidx -c /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 Precise Pangolin 12.04 Installer Bug reports ================================================================= Please log any installer bug reports at http://bugs.koha-community.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: Free Software Foundation 51 Franklin Street, Fifth Floor Boston, MA 02110-1301 USA Or visit their website: http://www.fsf.org/