Merge branch 'bug_7678' into 3.12-master

[koha.git] / INSTALL.ubuntu.12.04

=================================================================
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 three suggested ways to install Koha. If you will be
  participating in Koha's development, the Download from Git
  is the recommended way (See 1.5.1 below).
  If you would like to skip some of these tedious tasks, visit
  the following URL:
  http://wiki.koha-community.org/wiki/Koha_3.8_on_Debian_Squeeze
  If you will not be, then follow the Download from Tarball
  instructions (See 1.5.2 below).

  1.5.1 Download from 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.2 Download from 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
    $ ./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:
    $ ./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 <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:
      <path/to/koha>/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://<servername>: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 <language-code>

  <language-code> 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 <listen> 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 <kohauser>, <kohapassword, and <kohadatabasename>
  need to be substituted on the following commands:
   $ mysql -u<kohauser> -p<kohapassword>
   mysql> drop database <kohadatabasename>;


2b. Remove Indexes:

  To help determine what <prefix> 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 <prefix>
  is '/etc/koha'.

  Once you know the value of prefix, run these commands
  substituting in the correct value:
   $ zebraidx -c <prefix>/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
   $ zebraidx -c <prefix>/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/