Koha/INSTALL.ubuntu

=================================================================
Instructions for Installing Koha from Source
=================================================================

BUG REPORTS AND FEEDBACK
=================================================================

This document last modified: 18 September 2013

Given the nature of documentation to become outdated, or have
problems, please either submit feedback or bug reports.

Bug reports can be posted at http://bugs.koha-community.org

Feedback can be posted on the Koha Developer's List:
http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel


INTRODUCTION
=================================================================

These are the instructions for installing Koha from source. They
have been tested using Ubuntu 12.04 LTS. The copyright,
licensing, and other details have been put at the end, so the
installation can be started as soon as possible.

'nano' is a generic text editor. Please feel free to substitute
your favourite editor (vi, emacs, or etc.).

To install Koha for production, it is recommended that you use
packages. Installing from packages is not the same as installing
from source. These are not your recommended instructions for
production servers.

For instructions on how to install Koha on Ubuntu from packages, please
consult http://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages

To help assist with the development and improvement of Koha,
continue with these instructions and read more about version
control using git! See USEFUL REFERENCE LINKS below.

These instructions are intended for those who are skilled.
They can be used to set up a development system. This install
may not be as easy or smooth as you wish. This is to be expected
when installing from source.


NOTATION
=================================================================

Commands are indented by 4 spaces, and should be relatively obvious
as commands. Commands may have blank lines between them to
indicate that you should not just copy and paste the entire block
of commands.

File contents will be surrounded by the plus symbols with a
"FILE FULL" or "FILE PARTIAL" and the filename above the plus
symbols surrounding file contents.

Koha is released monthly, so keeping documentation up to date
is difficult. The convention is to replace the last number with
an x. For example, the current version is part of the 3.14.x
series and the former stable version is the 3.12.x series.


INSTALL UBUNTU
=================================================================

These instructions assume that you have already installed Ubuntu
from the official site: http://www.ubuntu.com/download/server

There is no need to install extra packages during the Ubuntu
installation. Apache2 and MySQL will be installed in the
instructions later.

Installing a mail transfer agent before installing Koha will
prevent the installation of nullmailer. Such an installation
and configuration of a mail transfer agent is beyond the
scope of this document. Consult your system administrator,
network administrator, or IT Department for assistance as needed.

These instructions assume you created a user account with your
login credentials and not one called 'koha'. This is to prevent
the system user 'koha' from having more permissions than it should.


ADD A KOHA COMMUNITY REPOSITORY
=================================================================

These instructions still function even though the latest version
of Debian is wheezy. If the version has changed again, please
confirm these instructions on the mailing list or IRC channel.

To avoid getting prompted for a password in the middle of a
chain of commands type the following:
    sudo ls

IF YOU ARE DOING A STANDARD (tarball) INSTALL use the following
command:
    echo deb http://debian.koha-community.org/koha squeeze main \
        | sudo tee /etc/apt/sources.list.d/koha.list

IF YOU ARE DOING A DEV (typically git) INSTALL use the following
command:
    echo deb http://debian.koha-community.org/koha squeeze-dev main \
        | sudo tee /etc/apt/sources.list.d/koha.list

To use the older stable release:
echo deb http://debian.koha-community.org/koha oldstable main \
| sudo tee /etc/apt/sources.list.d/koha.list
Intentionally not indented, as the others are preferred.

FOR EITHER INSTALLATION:
Add the key in gpg.asc to your APT trusted keys to avoid
warning messages on installation:
    wget -O- http://debian.koha-community.org/koha/gpg.asc \
        | sudo apt-key add -


UPDATE UBUNTU
=================================================================

This process, particularly the upgrade step, may take a while.

    sudo apt-get update

    sudo apt-get upgrade

    sudo apt-get clean


DOWNLOAD THE LATEST KOHA RELEASE
=================================================================

There are two ways to grab the source, either by using git
or by downloading the .tar.gz file. Git is recommended for a
development environment.

IF YOU ARE DOING A STANDARD INSTALLATION:
Downloading Source Via Tarball
=================================================================

    wget http://download.koha-community.org/koha-latest.tar.gz
    tar xvf koha-latest.tar.gz
    ls

NOTE: You need to cd into the Koha directory, but since the
version changes, you'll know by the ls command what it is.

IF YOU ARE DOING A DEV INSTALLATION:
Downloading Source Via Git
=================================================================

Please see the following wiki page and follow the instructions up
to and including "git checkout -b mywork origin".
http://wiki.koha-community.org/wiki/Version_Control_Using_Git


INSTALL DEPENDENCIES
=================================================================

Dependencies from Repository
=================================================================

The repository added has koha-deps and koha-perldeps packages
which make it very easy. Type the following:
    sudo apt-get install koha-deps koha-perldeps make

Check For Missing Dependencies
=================================================================

Check everything was installed, by running the test script to
identifty missing libraries:
    ./koha_perl_deps.pl -m -u

Install any required libraries that are missing. It is a good
idea to install optional ones that are easily found as well.


CREATE MYSQL DATABASE AND GRANT PRIVILEGES
=================================================================

Create MySQL Database
=================================================================

If you have difficulty accessing MySQL's root acount, perhaps
this Ubuntu page on resetting the root password may help.
https://help.ubuntu.com/community/MysqlPasswordReset

    mysql -u root -p

    CREATE DATABASE kohadata;

The Koha database has now been created with the name kohadata.

Create User and Grant Permissions
=================================================================

Continue entering MySQL commands. SUBSTITUTE A PASSWORD OF YOUR
CHOICE FOR THE {PASSWORD}'S IN THE FOLLOWING COMMANDS:

    CREATE user 'koha'@'localhost' IDENTIFIED by '{PASSWORD}';
    GRANT ALL ON kohadata.* TO 'koha'@'localhost' IDENTIFIED BY '{PASSWORD}';
    FLUSH PRIVILEGES;
    QUIT

The Koha administrative user has now been created with the name
'koha' and the password of your choosing.


CONFIGURE KOHA
=================================================================

User/Group Environment Variables
=================================================================

IF YOU ARE DOING A STANDARD INSTALLATION, then create a
separate 'koha' system user:
    sudo adduser koha

There is no need to set the following environment variables,
because 'koha' is the default account to use.

IF YOU ARE DOING A DEV INSTALLATION, then create some
environment variables for the process to pick up and use later:
    export __KOHA_USER__=$USER
    export __KOHA_GROUP__=$USER
    echo $USER

The output of the echo command should match your user id,
and since the user id and group id are generally the same for
a freshly created account, this will make sure the indexing
happens as this account.


Configure Your Koha Install
=================================================================

    perl Makefile.PL

How you answer the first question will affect where things will
end up being placed. It is recommended that choose 'standard' if
you are doing a tarball install, and 'dev' if you are doing a
git install.

Answering the resulting questions requires thinking. Here are
some hints.

Recall that the database created is kohadata set in the Create
MySQL Database step. The username and password were set up in
the Create User and Grant Permissions step.

Give some thought should be given to the MARC format desired
and the method of character normalization (chr or icu), though
the defaults will work as MARC21 just fine.

Use the same username and password for the Zebra questions.

Don't worry about warnings generated by optional components.


Build And Test Koha
=================================================================

Having configured Koha, build it using the following command:
    make

Once this has successfully run, test Koha using the following
command:
    make test

Don't worry about the large number of scary warning scrolling
by. All that matters is "PASS" or "FAIL".

If this fails, it is likely due to a failed dependency. Remember,
a source installation is not always smooth. You can determine the
missing dependency by scrolling back and looking for something
like: Can't locate Cache/Memcached/Fast.pm in @INC
Install it, and try to build and test again.


Install Koha
=================================================================

Once the make test has successfully run, install Koha.

IF YOU ARE DOING A STANDARD INSTALLATION, using the
following command (follow any on screen prompts):
    sudo make install

Once this has successfully run, Koha is almost installed. There
are only a few more steps left.

IF YOU ARE DOING A DEV INSTALLATION, using the
following command (follow any on screen prompts):
    make install

No sudo is required as you have access to the directories
listed above.

FOR EITHER INSTALLATION:
Near the end of this command, the output will have two lines
containing KOHA_CONF and PERL5LIB in them.  Take note of the two
export commands as you will need them for a later step.


PRE-WEB INSTALL SETUP
=================================================================

Ubuntu MySQL Security Tweak
=================================================================

There is a security risk in Ubuntu's MySQL default setup. Type
the following commands:
    mysql -u root -p

    USE mysql;
    DELETE FROM user WHERE user='';
    FLUSH PRIVILEGES;
    QUIT

The anonymous connections are now removed.


Configure System Wide Environment Variables
=================================================================

Running scripts and cron jobs requires environment variables set.
Use the following commands:
    sudo nano /etc/environment

IF YOU ARE DOING A DEV INSTALLATON:
FILE PARTIAL (ADD): /etc/environment
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
KOHA_CONF=/home/{YOUR USER NAME}/koha-dev/etc/koha-conf.xml
KOHA_PATH=/home/{YOUR USER NAME}/kohaclone
PERL5LIB=/home/{YOUR USER NAME}/kohaclone
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
NOTE: CHANGE {YOUR USER NAME} TO YOUR ACTUAL USER NAME!

IF YOU ARE DOING A STANDARD INSTALLATON:
FILE PARTIAL (ADD): /etc/environment
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
KOHA_CONF=/etc/koha/koha-conf.xml
KOHA_PATH=/usr/share/koha
PERL5LIB=/usr/share/koha/lib
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

    logout

You need to logout and back in in order to get the environment
variables values to be recognized.


CONFIGURE AND START APACHE
=================================================================

Place Koha Site File
=================================================================

IF YOU ARE DOING A DEV INSTALLATION, use the following command:
    sudo ln -s ~/koha-dev/etc/koha-httpd.conf \
        /etc/apache2/sites-available/koha

IF YOU ARE DOING A STANDARD INSTALLATION, use the following
command:
    sudo ln -s /etc/koha/koha-httpd.conf \
        /etc/apache2/sites-available/koha

Tweak Koha Site File
=================================================================

The default file limits connections to those from 127.0.1.1
(or 127.0.0.1), which is rather difficult to test/use in a
server environment. Edit the file:
    sudo nano /etc/apache2/sites-available/koha

/etc/apache2/sites-available/koha will have a line
that should have the IP address changed to a *.
FILE PARTIAL (CHANGE): /etc/apache2/sites-available/koha
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
<VirtualHost *:80>
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

/etc/apache2/sites-available/koha will have another line
that should have the IP address changed to a *
FILE PARTIAL (CHANGE): /etc/apache2/sites-available/koha
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
<VirtualHost *:8080>
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Setup Default Ports
=================================================================

    sudo nano /etc/apache2/ports.conf

/etc/apache2/ports.conf must have two lines exactly like
the following.  Do not add them if they are already there.

FILE PARTIAL (CONFIRM/ADD/CHANGE): /etc/apache2/ports.conf
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Listen 80
Listen 8080
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

/etc/apache2/ports.conf does not require NameVirtualHost.
Do not add it if it is missing or already there. Just
prepend # accordingly.

FILE PARTIAL (CONFIRM/ADD/CHANGE): /etc/apache2/ports.conf
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
#NameVirtualHost *:80
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Disable Default Site
=================================================================

These short instructions assume that the default site is
not needed.  Talk with your system administrator, network
administrator, or IT Department to CONFIRM THIS BEFORE RUNNING
the following command:
    sudo a2dissite 000-default

Enable Modules and Site
=================================================================

Now enable the Apache modules this config needs, enable Koha's
virtual host configuration, and restart Apache.
    sudo a2enmod rewrite
    sudo a2enmod deflate
    sudo a2ensite koha
    sudo service apache2 restart


SETUP ZEBRA
=================================================================

The Zebra process send responses to search requests sent by Koha
or Z39.50/SRU/SRW clients.

The user you run Zebra as will be the only user with write
permission on the Zebra index. For a standard installation, this
should be the system user 'koha'. For a dev installation, this
should be your system user.

Start Zebra Server on Boot
=================================================================

IF YOU ARE DOING A STANDARD INSTALLATION, use this command:
    sudo ln -s /usr/share/koha/bin/koha-zebra-ctl.sh \
        /etc/init.d/koha-zebra-daemon

IF YOU ARE DOING A DEV INSTALLATION, use this command:
    sudo ln -s ~/koha-dev/bin/koha-zebra-ctl.sh \
        /etc/init.d/koha-zebra-daemon

FOR EITHER INSTALLATION:
    sudo update-rc.d koha-zebra-daemon defaults
    sudo service koha-zebra-daemon start

Configuring Zebra Indexing
=================================================================

IF YOU ARE DOING A STANDARD INSTALLATION, use this command:
    sudo nano /etc/cron.d/koha

FILE FULL: /etc/cron.d/koha
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# The cronjobs -- $KOHA_PATH is defined in /etc/environment, and
# gets set when this process runs as a user (koha).
*/5 * * * * koha $KOHA_PATH/bin/migration_tools/rebuild_zebra.pl -b -a -z &> /dev/null
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

IF YOU ARE DOING A DEV INSTALLATION, use this command:
    crontab -e

FILE PARTIAL (ADD):
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# The cronjobs -- $KOHA_PATH is defined in /etc/environment, and
# gets set when this process runs.
*/5 * * * *	$KOHA_PATH/misc/migration_tools/rebuild_zebra.pl -b -a -z &> /dev/null
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


SETUP ADDITIONAL LANGUAGES
=================================================================

To use multi-lingual sample data, please install languages
which may be useful for use in the Koha system.

Information on this can be found:
http://wiki.koha-community.org/wiki/Installation_of_additional_languages_for_OPAC_and_INTRANET_staff_client


WEB INSTALLATION
=================================================================

Now you can visit your staff client website to continue with the
Koha web installer. The user name to log in with will be koha.

The password will be what you set in the 'Create User and
Grant Permissions' section above.

Lynx navigational keys include: tab to go between fields, enter
(when not on text fields) to toggle or click, space to change
pages (when not on text fields), Q to quit (when not on text
fields). Arrows also work.

    sudo apt-get install lynx

    lynx http://127.0.1.1:8080/


SET UP YOUR LIBRARY IN KOHA
=================================================================

After the web install, you should be redirected to:
http://127.0.1.1:8080
Follow these steps:
- Login with koha user name and password.
- Click on the More dropdown menu.
- Select and click Administration.
- Click Libraries and groups
  under the Basic Parameters heading.
- Click New Library and enter your information into the form.
- Click Submit.
Your library is now set up in Koha.

Take the time to read the documentation to do other necessary
setup tasks such as creating a patron, and importing or entering
MARC data. The documentation for Koha can be found at:
http://koha-community.org/documentation/


USEFUL REFERENCE LINKS
=================================================================

Documentation:
http://koha-community.org/documentation/

Additional Languages:
http://wiki.koha-community.org/wiki/Installation_of_additional_languages_for_OPAC_and_INTRANET_staff_client

Stage MARC Records for Import:
http://manual.koha-community.org/3.14/en/catalogtools.html#stagemarc
NOTE: The URL has been similar since Koha version 3.8

Frequently Asked Questions:
http://koha-community.org/documentation/faq

Bug Reports:
http://bugs.koha-community.org/

Public Z39.50/SRU server:
http://wiki.koha-community.org/wiki/Troubleshooting_Koha_as_a_Z39.50_server

Alternate Indexing Method:
http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra


UPGRADING
=================================================================

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.

First, ensure the most recent dependencies are installed:
    sudo apt-get update
    sudo apt-get install koha-deps koha-perldeps

IF YOU ARE DOING A STANDARD UPGRADE:
In order to upgrade, find the path to the koha install-log file:
    sudo find /usr/share/koha/ -name 'koha-install-log'

Change directory into the latest koha source directory, and then:
    perl Makefile.PL --prev-install-log /path/to/koha-install-log

NOTE: Make sure to change the /path/to/koha-install-log to the
one that was found.

    make
    make test

And if that passes:
    sudo make upgrade

IF YOU ARE DOING A DEV UPGRADE:
In order to upgrade, find the path to the koha install-log file:
    find ~/koha-dev/ -name 'koha-install-log'

    cd ~/kohaclone
    perl Makefile.PL --prev-install-log /path/to/koha-install-log

NOTE: Make sure to change the /path/to/koha-install-log to the
one that was found.

    make
    make test

And if that passes:
    make upgrade

FOR EITHER UPGRADE TYPE:
If you are upgrading from a version of Koha earlier than 3.4.x,
Koha 3.4.x or later no longer stores items in biblio records:
./misc/maintenance/remove_items_from_biblioitems.pl --run
Intentionally not indented, in the hopes that most upgrades are
post 3.4.x.

Regardless of version you are upgrading from, a full reindex is
always the best option:
IF YOU ARE DOING A STANDARD UPGRADE
    sudo su -l koha --command="/usr/bin/perl /usr/share/koha/bin/migration_tools/rebuild_zebra.pl -b -a -r -v"

IF YOU ARE DOING A DEV UPGRADE
    ./misc/migration_tools/rebuild_zebra.pl -b -a -r -v


UNINSTALL INSTRUCTIONS
=================================================================

Stop Services
=================================================================
    sudo a2dissite koha
    sudo rm /etc/apache2/sites-available/koha
    sudo service apache2 restart
    sudo update-rc.d koha-zebra-daemon remove
    sudo rm /etc/init.d/koha-zebra-daemon

Remove Database
=================================================================
    mysql -u koha -p

    drop database kohadata;
    quit

Remove Indexes
=================================================================

IF DOING A STANDARD REMOVAL:
    zebraidx -c /etc/koha/zebradb/zebra-biblios.cfg \
        -g iso2709 -d biblios init
    zebraidx -c /etc/koha/zebradb/zebra-authorities.cfg \
        -g iso2709 -d authorities init
    sudo rm -rf /etc/koha
    sudo rm -rf /usr/share/koha
    sudo rm /etc/cron.d/koha

You may wish to follow up with:
    sudo find / -t d -name "koha"
to help find any remnants.

IF DOING A DEV REMOVAL:
The following will work, but is very dangerous! Please copy or
type this correctly.
    zebraidx -c ~/koha-dev/etc/zebradb/zebra-biblios.cfg \
        -g iso2709 -d biblios init
    zebraidx -c ~/koha-dev/etc/zebradb/zebra-authorities.cfg \
        -g iso2709 -d authorities init
    rm -rf ~/koha-dev
    rm -rf ~/kohaclone
NOTE: Don't forget to remove the crontab entries!


LICENSE
=================================================================

This file is part of Koha.

Major re-write by Mark Tompsett
Copyright (C) 2013

Based on remnants by:
Copyright (C) 2007, 2008 LibLime (http://liblime.com)
                          Original author: Joshua Ferraro
Some parts Copyright (C) 2010 Chris Nighswonger (modified for ubuntu)
                          (cnighswonger AT foundations DOT edu)
Some parts Copyright (C) 2012 Tomas Cohen Arazi
                          (tomascohen AT gmail DOT com)
Some parts Copyright (C) 2012 Mark Tompsett
                          (mtompset AT hotmail DOT com)

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 3 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, see <http://www.gnu.org/licenses>.