Introduction

DO NOT USE THESE INSTRUCTIONS ON A FORWARD BASIS!

These instructions will be tested with Ubuntu 12.04 LTS specifically. We strongly recommend an LTS release, though anything higher than 12.04 should work.

The current supported versions of Koha include newer libraries, which are not easily available under previous LTS releases. So please, do not attempt to install Koha on anything prior to Ubuntu 12.04 LTS. Your success may vary, and you will not be supported.

We do not wish to engaged in the editor-wars, so whenever you see 'nano', feel free to substitute your favourite editor (vi, emacs, etc.).

There are three ways to install Koha: packages, git and tarball. These instructions focus on the tarball installation. This is for historical purposes only. The packages method of installation is the recommended method. Packages effectively do most of the difficult work. You can read the Debian package instructions for additional information. If you are able to assist with the development and improvement of Koha and this isn't for a production environment, consider installing a git version. Git is a version control system. Try to learn version control using git!

The packages install, the git install, and the tarball install all have different directory structures. Do not attempt to correct packages or git problems by following these instructions afterwards.

Pre-Installation Setup

Notation

Lines beginning with # or $ mean the suffix is a command that should be executed on the shell. That is, the part after given prompt. Don't type or copy the # or $ part. For instance:

$ sudo su -
...
# echo "Hello world"

means to run the commands sudo su - and echo "Hello world".

Lines beginning with > mean the suffix is a command that should be run within a MySQL or CPAN shell. For example,

> SHOW DATABASES;

will show the available databases on a MySQL server.

Similarly,

> install Template

Would mean to run install Template in the CPAN program.

Koha is released monthly, so keeping documentation up to date is difficult. Rather than saying 3.8.1, 3.8.2, 3.8.3, 3.8.4, or any other specific number, the convention is to replace the last number with an x. For example, the current version is part of the 3.8.x series and the former stable version is the 3.6.x series.

Install Ubuntu

Download and install Ubuntu from the official site.

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 extra packages during the installation of Ubuntu.

Add A Koha Community Repository

With the installation of Ubuntu done, you will need to tweak your repositories to install perl libraries which may not exist in the default Ubuntu repositories. So before we start, let's do:

$ sudo ls

This prevents the next command from looking like it hung when it is actually waiting for a password. Now, let's get the signing key:

$ wget -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -

To install the repository for the latest stable release, which is recommended, use the following command:

$ echo deb http://debian.koha-community.org/koha squeeze main | sudo tee /etc/apt/sources.list.d/koha.list

There are currently three active repositories: oldstable, squeeze, and squeeze-dev. As of 2012-09-09, 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 important to note that when 3.10.0 is released, there will be no repository available for 3.6.x as 3.8.x will be moved to oldstable. This type of change happens roughly every 6 months.

If the latest version of Debian is no longer squeeze, please confirm these instructions on the mailing list or IRC channel.

Update Ubuntu

Now that you have added the appropriate repository, check to make sure Ubuntu is up to date. You may be prompted for the password of the user account you are signed in as.

$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt-get clean

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

Add 'koha' User

Add a user for installing koha and running zebra:

$ sudo adduser koha

This is the user that should own all the installed files upon completion. This is the user that should be running the zebra indexing process.

Configuring the Character Set (Part 1)

Your locale should be set to UTF-8. This step is very important for a UNICODE compliant system.

Run the Locale command and it should show you using UTF-8:

$ locale
LANG=en_PH.UTF-8
LANGUAGE=
LC_CTYPE="en_PH.UTF-8"
LC_NUMERIC="en_PH.UTF-8"
LC_TIME="en_PH.UTF-8"
LC_COLLATE="en_PH.UTF-8"
LC_MONETARY="en_PH.UTF-8"
LC_MESSAGES="en_PH.UTF-8"
LC_PAPER="en_PH.UTF-8"
LC_NAME="en_PH.UTF-8"
LC_ADDRESS="en_PH.UTF-8"
LC_TELEPHONE="en_PH.UTF-8"
LC_MEASUREMENT="en_PH.UTF-8"
LC_IDENTIFICATION="en_PH.UTF-8"
LC_ALL=

If so, skip to the following Installation Method section.

If it is not set to something UTF-8, determine what locales are installed:

$ locale -a
C
en_AG
en_AU.utf8
en_BW.utf8
en_CA.utf8
en_DK.utf8
en_GB.utf8
en_HK.utf8
en_IE.utf8
en_IN
en_NG
en_NZ.utf8
en_PH.utf8
en_SG.utf8
en_US.utf8
en_ZA.utf8
en_ZW.utf8
POSIX

Select one (note that utf8 becomes UTF-8) and use it:

$ sudo update-locale LANG=en_US.UTF-8

Log out of Ubuntu and log back into Ubuntu to see the locale change reflected when you use the locale command.

Recheck your locale ends in UTF-8 now.

$ locale

Installation Method

At this point, it is recommended to do a packages installation as it will simplify installation and upgrade steps later. If development and patching will be done, consider using a git installation. For historical purposes only, these tarball instructions are provided.

Download the latest Koha release

There are two options for downloading Koha source to build: git and tarball. Since Koha version 3.4, there is no reason to use a tarball install under Ubuntu. The packages method of installation have been running well in production. Git is recommended for a development environment only. Either a packages installation or a git installation can be used in a testing environment.

Sources are available at http://download.koha-community.org
Issuing the following command you can get the latest stable release:

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

Though previous versions are available for download, only the stable and maintenance releases are supported.

Install Dependencies

Determine Build Directory

It may look like:

$ ls
koha-3.08.05  koha-latest.tar.gz

Change directory into your build directory.

Ubuntu Packages from Repository

All the required libraries have been added to a repository item. There is no need to use the old 'dselect' method any more. The old way had multi-architecture issues under 64-bit installations.

Type the following:

$ sudo apt-get install koha-deps koha-perldeps make

Ubuntu Packages for Perl Dependencies

Check everything was installed, by running the test script to identify missing libraries:

$ ./koha_perl_deps.pl -m -u

If the items listed are not required or the list is empty, proceed to the next section.

Try the following command:

$ aptitude -h

If aptitude is not installed, install it:

$ sudo apt-get install aptitude
$ sudo apt-get update

If there are any dependencies which are missing or need upgrading, first attempt aptitude searches. It is not necessary to install things that aren't required, but it may be more helpful in the future when functionality requirements may increase.

The following are examples only, and not necessarily the exact commands to be typed. The aptitude and apt-get commands will be used. But the exact commands will be determined by a series of commands initially resulting from the ./koha_perl_deps.pl -m -u command.

For example, if Template::Plugin::HtmlToText is listed as required, then take the name and use it to make a similar aptitude search command:

$ aptitude search libtemplate-plugin-htmltotext-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. If there is no output, there is no apt-get install command to get it. If there is output, then a simple apt-get install can be done, if Template::Plugin::HtmlToText was missing or needed upgrading:

$ sudo apt-get install libtemplate-plugin-htmltotext-perl

By using aptitude searches based on the results of the ./koha_perl_deps.pl -m -u command, it is quite likely that some libraries will be added with apt-get without using CPAN.

Do this for all the required dependencies listed. Then re-run the command:

$ ./koha_perl_deps.pl -m -u

Installed Required Module is
Module Name Version Version Required
--------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------
Total modules reported: 0 * Module is missing or requires an upgrade.

In general, the repositories on debian.koha-community.org should have any missing pieces. The list should be empty like above.

Here is an example of what you might see:

$ ./koha_perl_deps.pl -m -u

                                              Installed         Required          Module is
Module Name                                   Version           Version            Required
--------------------------------------------------------------------------------------------
Template::Plugin::HtmlToText                  0 *               0.03                    Yes
Test::YAML::Valid                             0 *               0.04                    No

--------------------------------------------------------------------------------------------
Total modules reported: 2                      * Module is missing or requires an upgrade.

This required Template::Plugin::HtmlToText to be installed, because the "Required" column is "Yes". So, if after all this processing, the items listed are not required, proceed to the next section.

Perl dependencies via Unmarked Ubuntu Repositories

Sometimes the libraries are actually in the repositories, but because they do not have a candidate number, they won't be installed or listed. This is from a fresh install of Ubuntu 10.04 LTS (not recommended) attempting to install version 3.8.4 of Koha. The following output is an example only. First, determine the list of missing libraries:

$ ./koha_perl_deps.pl -m -u
                                              Installed         Required          Module is
Module Name                                   Version           Version            Required
--------------------------------------------------------------------------------------------
HTTP::OAI                                     0 *               3.2                     Yes
Locale::Currency::Format                      0 *               1.28                    Yes
Memoize::Memcached                            0 *               0.03                    No
PDF::API2::Simple                             0 *               1                       Yes
Text::CSV::Encoded                            0 *               0.09                    Yes
DateTime                                      0.52 *            0.58                    Yes
DateTime::TimeZone                            1.10 *            1.26                    Yes
Template                                      2.20 *            2.22                    Yes
Test::Strict                                  0.13 *            0.14                    No
--------------------------------------------------------------------------------------------
Total modules reported: 9                      * Module is missing or requires an upgrade.

The ones that are installed but need upgrading likely are in main, while the others are likely in universe. You may discover a particular installation order is required to get them to work as well.

One can find these by browsing to an appropriate repository on the web, such as:

http://au.archive.ubuntu.com/ubuntu/pool

Notice how they are filed in a manner similar to the aptitude searches we attempted. This is an example only:

wget http://au.archive.ubuntu.com/ubuntu/pool/universe/libh/libhttp-oai-perl/libhttp-oai-perl_3.24-1_all.deb
wget http://au.archive.ubuntu.com/ubuntu/pool/universe/libl/liblocale-currency-format-perl/liblocale-currency-format-perl_1.30-1_all.deb
wget http://au.archive.ubuntu.com/ubuntu/pool/universe/libp/libpdf-api2-simple-perl/libpdf-api2-simple-perl_1.1.4u-3_all.deb
wget http://au.archive.ubuntu.com/ubuntu/pool/universe/libt/libtext-csv-encoded-perl/libtext-csv-encoded-perl_0.10-2_all.deb
wget http://au.archive.ubuntu.com/ubuntu/pool/universe/libd/libdatetime-timezone-perl/libdatetime-timezone-perl_1.35-1+2011h_all.deb
sudo dpkg -i libhttp-oai-perl_3.24-1_all.deb liblocale-currency-format-perl_1.30-1_all.deb
sudo dpkg -i libpdf-api2-simple-perl_1.1.4u-3_all.deb
sudo dpkg -i libtext-csv-encoded-perl_0.10-2_all.deb

However, you may encounter dependency issues and need to find another library. For example:

wget http://au.archive.ubuntu.com/ubuntu/pool/universe/libc/libclass-load-perl/libclass-load-perl_0.06-1_all.deb
sudo dpkg -i libclass-load-perl_0.06-1_all.deb
sudo dpkg -i libdatetime-timezone-perl_1.35-1+2011h_all.deb

Sometimes installation will require knowing if you are using a 32-bit or 64-bit operating system. Sometimes it will require unravelling several levels of dependencies. Both libraries, DateTime and Template, may require such detail. As such, though it is not recommended, CPAN is a simpler way to continue.
You only need to look for the required dependencies. That is why in this example, we did not go looking for Memoized::Memcached or Test::Strict.

Perl dependencies via CPAN

If you reach this stage, please ask for the missing libraries to be placed in the debian.koha-community.org repository. This will help others and you. Additionally, if you reach this stage, please consider doing a packages install.

IMPORTANT: You should only use CPAN for Perl dependencies which are not available from the package maintainer. You have been warned!

Do not run CPAN just to install things listed which are not required. CPAN installs can make upgrading more difficult on
a forward basis, and can be a source of debugging headaches.

Install some dependencies:

$ sudo apt-get install zip unzip

Run CPAN:

$ sudo cpan

The first time CPAN configuration asks many questions. If this is your first time running CPAN, make sure the configuration gets saved:

> o conf commit
> quit

Make sure to get a list of what you need to install:

$ ./koha_perl_deps.pl -m -u

The following is an example of what a former install may have required. Whatever is listed as a result of running the ./koha_perl_deps.pl -m -u command will be used instead. Only the required ones must be install. Do not use "force install" unless an "install" fails.

$ sudo cpan
> force install HTTP::OAI
> install Business::ISBN 2.05
> install CGI::Session::Driver::memcached 0.04
> install Gravatar::URL 1.03
> install Memoize::Memcached 0.03
> install Text::CSV::Encoded 0.09
> quit

Confirm that all required libraries are installed:

$ ./koha_perl_deps -m -u
                                              Installed         Required          Module is
Module Name                                   Version           Version            Required
--------------------------------------------------------------------------------------------
Graphics::Magick                              0 *               1.3.05                  No
--------------------------------------------------------------------------------------------
Total modules reported: 0                      * Module is missing or requires an upgrade.

If you are unable to get all the required dependencies installed, and you are using Ubuntu, please wait for the repository maintainers to add the missing requirements.

If you are attempting a tarball install, please follow the recommendations and do a package install. Git installations are best for development or testing environments. Package installations are best for production or testing environment.

Create MySQL Database and Grant Privileges

Update 'root' MySQL Password

If you were not prompted to set the MySQL password during the installation of MySQL:

$ sudo mysqladmin password {root password of your choosing}

If you are having difficulty accessing MySQL's root acount, perhaps this Ubuntu page on resetting the root password may help.

Create MySQL Database

$ mysql -u root -p
Enter mysql root password:
> CREATE DATABASE kohadata;
> SHOW DATABASES;

The koha database has now been created with the name kohadata. It should now be listed.

Create User and Grant Permissions

Continue entering MySQL commands. Substitute a password of your choice for the {koha user password}'s in the following commands:

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

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

Test to make sure the SAX Parser is setup correctly

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.

If it reports bad, and it probably will the first time, the ParserDetails.ini file needs to be edited.

Unfortunately, because not all packages for the XML SAX Parser are packaged in the same location, there could be more than one ParserDetails.ini file. They are easily found, however, using the following command:

$ sudo find / -name "ParserDetails.ini"
/usr/local/share/perl/5.10.1/XML/SAX/ParserDetails.ini
/usr/share/perl5/XML/SAX/ParserDetails.ini
/etc/perl/XML/SAX/ParserDetails.ini

Another installer noted that they had to change the /usr/local/share/perl/5.12.4/XML/SAX/ParserDetails.ini file. This is why this find command is very important.

Only one example will be provided. A similar editing process is required on all of the files found. All of the resulting files should be kept identical.

So edit the file:

$ sudo nano /etc/perl/XML/SAX/ParserDetails.ini

Notice that there are four lines in a block? Move the block of four lines (two lines and two blank lines) that look like this:

[XML::LibXML::SAX::Parser]
http://xml.org/sax/features/namespaces=1

from their current location to the bottom of the file. Repeat this for all the files found. Make sure all the ParserDetails.ini files are identical.

Run the test again:

$ ./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.

Configure Koha

Type of Install

Select defaults except as noted. Answer the default standard.

$ perl Makefile.PL
unable to locate Koha configuration file koha-conf.xml at /home/{your user name}/.../C4/Context.pm line 360.

By default, Koha can be installed in one of three ways:

standard: Install files in conformance with the Filesystem
          Hierarchy Standard (FHS). This is the default mode
          and should be used when installing a production
          Koha system. On Unix systems, root access is
          needed to complete a standard installation.

single:   Install files under a single directory. This option
          is useful for installing Koha without root access, e.g.,
          on a web host that allows CGI scripts and MySQL databases
          but requires the user to keep all files under the user's
          HOME directory.

dev:      Create a set of symbolic links and configuration files to
          allow Koha to run directly from the source distribution.
          This mode is useful for developers who want to run
          Koha from a git clone.

Installation mode (dev, single, standard) [standard]

Installation Directory

Accept the default. Since you answered standard it looks like:

Please specify the directory under which most Koha files
will be installed.

Note that if you are planning in installing more than
one instance of Koha, you may want to modify the last
component of the directory path, which will be used
as the package name in the FHS layout.

Base installation directory [/usr/share/koha]

User Account

The reason the default user and group 'koha' works is because that is what we created back in in the Add 'koha' user step. Continue with the default answers.

Since you are using the 'standard' install
mode, you should run 'make install' as root.
However, it is recommended that a non-root
user (on Unix and Linux platforms) have
ownership of Koha's files, including the
Zebra indexes if applicable.

Please specify a user account. This
user account does not need to exist
right now, but it needs to exist
before you run 'make install'. Please
note that for security reasons, this
user should not be the same as the user
account Apache runs under.

User account [koha]

Please specify the group that should own
Koha's files. As above, this group need
not exist right now, but should be created
before you run 'make install'.

Group [koha]

Database Engine

MySQL was intentionally installed and configured as part of these default instructions. Configuring an external MySQL server or setting up PostgreSQL is beyond the scope of these instructions. Continue answering with the default values.

Please specify which database engine you will use
to store data in Koha.  The choices are MySQL and
PostgreSQL; please note that at the moment
PostgreSQL support is highly experimental.

DBMS to use (Pg, mysql) [mysql]

Please specify the name or address of your
database server.  Note that the database
does not have to exist at this point, it
can be created after running 'make install'
and before you try using Koha for the first time.

Database server [localhost]

Please specify the port used to connect to the
DMBS [3306]

Database and Access Account

The following questions are based on the earlier setup. The database name was set up in the Create MySQL Database step. The database user name and password were set up in the Create User and Grant Permissions step. These are not defaults.

Please specify the name of the database to be
used by Koha [koha] kohadata

Please specify the user that owns the database to be
used by Koha [kohaadmin] koha

Please specify the password of the user that owns the
database to be used by Koha [katikoan] {koha user password}

Zebra Settings

If you continue to answer with defaults, it will install a working Koha. However, some thought should be given to the MARC format desired and the method of character normalization (chr or icu).

Koha can use the Zebra search engine for high-performance
searching of bibliographic and authority records.  If you
have installed the Zebra software and would like to use it,
please answer 'yes' to the following question.  Otherwise,
Koha will default to using its internal search engine.

Please note that if you choose *NOT* to install Zebra,
koha-conf.xml will still contain some references to Zebra
settings.  Those references will be ignored by Koha.

Install the Zebra configuration files? (no, yes) [yes]

Found 'zebrasrv' and 'zebraidx' in /usr/bin.

Since you've chosen to use Zebra with Koha,
you must specify the primary MARC format of the
records to be indexed by Zebra.

Koha provides Zebra configuration files for MARC21,
NORMARC and UNIMARC.

MARC format for Zebra indexing (marc21, normarc, unimarc) [marc21]

Koha supplies Zebra configuration files tuned for
searching either English (en) or French (fr) MARC
records.

Primary language for Zebra indexing (en, fr, nb) [en]

Koha can use one of  two different indexing modes
for the MARC bibliographic records:

grs1 - uses the Zebra GRS-1 filter, available
       for legacy support
dom  - uses the DOM XML filter; offers improved
       functionality.

Bibliographic indexing mode (dom, grs1) [dom]

Koha can use one of  two different indexing modes
for the MARC authorities records:

grs1 - uses the Zebra GRS-1 filter, available
       for legacy support
dom  - uses the DOM XML filter; offers improved
       functionality.

Authorities indexing mode (dom, grs1) [dom]

Zebra has two methods to perform records tokenization
and characters normalization: CHR and ICU. ICU is
recommended for catalogs containing non-Latin
characters. (chr, icu) [chr]

Zebra Database Access

The zebra user name and password are identical to the koha user name and password. These are not defaults.

Please specify Zebra database user [kohauser] koha

Please specify the Zebra database password [zebrastripes] {koha user password}

Miscellaneous

Details regarding configuring a SRU/Z39.50 server, using ParPaz2, installing a memcached server, and explaining the database independent tests are beyond the scope of these instructions. As such, continue by accepting the default values:

Since you've chosen to use Zebra, you can enable the SRU/
Z39.50 Server if you so choose, but you must specify a
few configuration options for it.

Please note that if you choose *NOT* to configure SRU,
koha-conf.xml will still contain some references to SRU
settings.  Those references will be ignored by Koha.

Install the SRU configuration files? (no, yes) [yes]

SRU Database host? [localhost]

SRU port for bibliographic data? [9998]

SRU port for authority data? [9999]

Since you've chosen to use Zebra, you can also choose to
install PazPar2, which is a metasearch tool.  With PazPar2,
Koha can perform on-the-fly merging of bibliographic
records during searching, allowing for FRBRization of
the results list.

Install the PazPar2 configuration files? [no]

Use memcached and memoize to cache the results of some function calls?
This provides a signficant performance improvement.
You will need a Memcached server running. (no, yes) [no]

Would you like to run the database-dependent test suite? (no, yes) [no]

Configuration Output

The script will then output what you have answered and write some configuration files. The warnings are nothing to be worried about, as the are optional components. The following is sample output for a tarball install:

Koha will be installed with the following configuration parameters:

AUTH_INDEX_MODE          dom
BIB_INDEX_MODE           dom
DB_HOST                  localhost
DB_NAME                  kohadata
DB_PASS                  {koha user password}
DB_PORT                  3306
DB_TYPE                  mysql
DB_USER                  koha
INSTALL_BASE             /usr/share/koha
INSTALL_MODE             standard
INSTALL_PAZPAR2          no
INSTALL_SRU              yes
INSTALL_ZEBRA            yes
KOHA_GROUP               koha
KOHA_INSTALLED_VERSION   3.08.04.000
KOHA_USER                koha
PATH_TO_ZEBRA            /usr/bin
RUN_DATABASE_TESTS       no
USE_MEMCACHED            no
ZEBRA_LANGUAGE           en
ZEBRA_MARC_FORMAT        marc21
ZEBRA_PASS               {koha user password}
ZEBRA_SRU_AUTHORITIES_POR9999
ZEBRA_SRU_BIBLIOS_PORT   9998
ZEBRA_SRU_HOST           localhost
ZEBRA_TOKENIZER          chr
ZEBRA_USER               koha

and in the following directories:

DOC_DIR                  $(DESTDIR)/usr/share/koha/doc
INTRANET_CGI_DIR         $(DESTDIR)/usr/share/koha/intranet/cgi-bin
INTRANET_TMPL_DIR        $(DESTDIR)/usr/share/koha/intranet/htdocs/intranet-tmpl
INTRANET_WWW_DIR         $(DESTDIR)/usr/share/koha/intranet/htdocs
KOHA_CONF_DIR            $(DESTDIR)/etc/koha
LOG_DIR                  $(DESTDIR)/var/log/koha
MAN_DIR                  $(DESTDIR)/usr/share/koha/man
MISC_DIR                 $(DESTDIR)/usr/share/koha/misc
OPAC_CGI_DIR             $(DESTDIR)/usr/share/koha/opac/cgi-bin
OPAC_TMPL_DIR            $(DESTDIR)/usr/share/koha/opac/htdocs/opac-tmpl
OPAC_WWW_DIR             $(DESTDIR)/usr/share/koha/opac/htdocs
PAZPAR2_CONF_DIR         $(DESTDIR)/etc/koha/pazpar2
PERL_MODULE_DIR          $(DESTDIR)/usr/share/koha/lib
SCRIPT_DIR               $(DESTDIR)/usr/share/koha/bin
SCRIPT_NONDEV_DIR        $(DESTDIR)/usr/share/koha/bin
ZEBRA_CONF_DIR           $(DESTDIR)/etc/koha/zebradb
ZEBRA_DATA_DIR           $(DESTDIR)/var/lib/koha/zebradb
ZEBRA_LOCK_DIR           $(DESTDIR)/var/lock/koha/zebradb
ZEBRA_RUN_DIR            $(DESTDIR)/var/run/koha/zebradb


To change any configuration setting, please run
perl Makefile.PL again.  To override one of the target
directories, you can do so on the command line like this:

perl Makefile.PL PERL_MODULE_DIR=/usr/share/perl/5.8

You can also set different default values for parameters
or override directory locations by using environment variables.

For example:

export DB_USER=my_koha
perl Makefile.PL

or

DB_USER=my_koha DOC_DIR=/usr/local/info perl Makefile.PL

If installing on a Win32 platform, be sure to use:
'dmake -x MAXLINELENGTH=300000'

Warning: prerequisite Test::Strict 0.14 not found.
Writing Makefile for koha
Writing MYMETA.yml

The directories listed will serve as a basis for uninstalling Koha, should you wish to do that later. They also show where things, like the code directories and error logs, will be found while using Koha.

Build, Test, and Install Koha

Having configured Koha, build it using the following command:

$ make

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

$ make test

Once this has successfully run, install Koha using the following command (follow any on screen prompts):

$ sudo make install

The sudo is required as a normal user does not have permissions to write things in /etc /var, etc.

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

At the end of this command, the output will look something like the following:

Koha's files have now been installed.

In order to use Koha's command-line batch jobs,
you should set the following environment variables:

export KOHA_CONF=/etc/koha/koha-conf.xml 
export PERL5LIB=/usr/share/koha/lib 

For other post-installation tasks, please consult the README.

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 set up. Type the following commands:

$ mysql -u root -p
> USE mysql;
> SELECT host,user FROM user;

Under Ubuntu, newer versions of MySQL include anonymous connections. This is a security risk. They are listed with no username. Continue entering MySQL commands.

> DELETE FROM user WHERE user='';
> SELECT host,user FROM user;

The anonymous connections should be removed now. Continue entering MySQL commands.

> FLUSH PRIVILEGES;
> QUIT

The anonymous connections are removed.

Configuring the Character Set (Part 2)

Apache2 and MySQL 5.5 should be set to UTF-8. This step is very important for a UNICODE compliant system.

Apache

Run the following command:

$ sudo nano /etc/apache2/conf.d/charset

Make sure the following lines are in the file and uncommented:

AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8

Restart Apache:

$ sudo service apache2 restart

MySQL

The goal of this step is to get the following output (or something very similar) demonstrating some sort of UTF8 and/or binary for the entries:

$ mysql -u root -p
Enter password:
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 38
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> show variables like '%colla%';
+----------------------+-----------------+
| Variable_name        | Value           |
+----------------------+-----------------+
| collation_connection | utf8_general_ci |
| collation_database   | utf8_general_ci |
| collation_server     | utf8_general_ci |
+----------------------+-----------------+
3 rows in set (0.01 sec)

mysql> show variables like '%char%';
+--------------------------+----------------------------+
| Variable_name            | Value                      |
+--------------------------+----------------------------+
| character_set_client     | utf8                       |
| character_set_connection | utf8                       |
| character_set_database   | utf8                       |
| character_set_filesystem | binary                     |
| character_set_results    | utf8                       |
| character_set_server     | utf8                       |
| character_set_system     | utf8                       |
| character_sets_dir       | /usr/share/mysql/charsets/ |
+--------------------------+----------------------------+
8 rows in set (0.02 sec)

mysql> quit
Bye
$

If your output matches the above, proceed to the next step: Configure System Wide Environment Variables

Tweaking my.cnf

If your output does not match the above, edit your mysql settings:

$ sudo nano /etc/mysql/my.cnf

Find the [mysqld] section and add the following lines (Works under MySQL version 5.5.24-0ubuntu0.12.04.1):

character-set-server=utf8
skip-character-set-client-handshake
innodb_file_per_table

To restart the mysql server use the following command:

$ sudo service mysql restart

If it fails to restart, edit your mysql settings:

$ sudo nano /etc/mysql/my.cnf

Then, replace the lines you added with the following (Works under MySQL version 5.1.63-0ubuntu0.10.04.1):

character-set-server=utf8
collation-server=utf8_general_ci
skip-character-set-client-handshake
innodb_file_per_table

restart the mysql server use the following command:

$ sudo service mysql restart

If your mysql server does not start, edit your mysql settings:

$ sudo nano /etc/mysql/my.cnf

Then, replace the lines you added with the following (Works for some versions less than MySQL 5.1.63):

init-connect='SET NAMES utf8'
character-set-server=utf8
collation-server=utf8_general_ci
character_set_client=utf8
innodb_file_per_table

The init-connect and character_set_client lines may not work and may prevent mysql from restarting depending on the version of MySQL installed.

As these are suggestions towards achieving the above goal, you may find them to not work in your case. In that case consult the manuals at dev.mysql.com/doc/index.html

Once you find a working combination, run the above MySQL tests again. Repeat until the MySQL tests show that UTF8 and/or binary are being used.

It would be wise to test Koha with some non-roman script characters in a title, and ensure that entry and retrieval work properly.

Configure System Wide Environment Variables

Running scripts and cron jobs requires environment variables set. Use the following commands:

$ sudo nano /etc/environment

For a recommended git installation confirm these lines are in the file:

KOHA_CONF=/etc/koha/koha-conf.xml 
KOHA_PATH=/usr/share/koha 
PERL5LIB=/usr/share/koha/lib

KOHA_CONF and PERL5LIB are very important to have defined.

Log out, and then log back in and run the following commands:

$ echo $KOHA_CONF
$ echo $KOHA_PATH
$ echo $PERL5LIB

Configure and Start Apache

Place Koha Site File

Link the koha apache configuration file:

$ 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 vi /etc/apache2/sites-available/koha

And change the two references from 127.0.1.1 (or 127.0.0.1) to *. The first match should to change should look like:

<VirtualHost *:80>

The second match to change should look like:

<VirtualHost *:8080>

Setup Default Ports

Then type the following command:

$ sudo nano /etc/apache2/ports.conf

Make sure both these Lines to the ports.conf file:

Listen 80 
Listen 8080

Port 8080 will be the staff client for administration. Port 80 will be for the OPAC.

If named virtual hosts will not be used, comment out any NameVirtualHost lines by prepending the # character to the line. They may look like the following:

#NameVirtualHost *:80
#NameVirtualHost *:8080

Disable or Edit Default Site

If there is more than just Koha websites on this machine, you may wish to:

$ sudo vi /etc/apache2/sites-enabled/000-default

And change the port number it uses:

<VirtualHost *:4080>

If the default site is not needed:

$ sudo a2dissite 000-default

Enable Modules and Site

Now enable the apache modules this config needs, enable koha's configuration, and restart apache.

$ sudo a2enmod rewrite
$ sudo a2enmod deflate
$ sudo a2ensite koha
$ sudo /etc/init.d/apache2 restart

Setup Zebra

Server to Start on Boot Up

Link the the koha zebra control file:

$ sudo ln -s /usr/share/koha/bin/koha-zebra-ctl.sh /etc/init.d/koha-zebra-daemon

Type the following command:

$ sudo update-rc.d koha-zebra-daemon defaults
$ sudo /etc/init.d/koha-zebra-daemon start

Configure Zebra Indexing

Add a cron job to index your zebra database:

$ sudo nano /etc/cron.d/koha

and add the following:

# The cronjobs -- $KOHA_PATH is defined in /etc/environment, and gets set when this process runs as a user (koha).

and then:

*/5 * * * * koha $KOHA_PATH/bin/migration_tools/rebuild_zebra.pl -b -a -z &> /dev/null

In the above crontab file, there are 5 (five) fields (minute, hour,day, month,day of week) followed by the user (koha) and the command to rebuild the zebra index. The '*/5' means every five minutes. If this process is running multiple times at the same time, this will mean your searches will not work properly. This is why some people prefer to do background indexing outside of a cron job. You can read more about that at http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra. Do not use both methods at the same time!

If you are not familiar with cron tab jobs, please follow these instructions without varying. Others have attempted to use a user cron job incorrectly or have changed the file ownership. This is not the same format as a user's cron job, "koha" is required. This will not list with a crontab -l command regardless of user. Do not try to fix an apparently missing crontab listing. Do not run this and a user version cron job. Also, the ownership of /etc/cron.d/koha should be root.root, which is the default from the sudo command, not koha.koha as one may attempt. Do not change the file's ownership.

Determining an IP Address

Assumptions

In a home or corporate LAN, it is quite likely that your network setup has been configured with DHCP. If you are being hosted externally however, your machine likely has been given a static IP address, or it may be behind a reverse proxy. Because of the many possible complex configurations of networking involved, these instructions will assume the former simpler case. Further questions can be asked on the mailing list or IRC channel, after you complete these instructions in the order as given and as written.

Private IP Addresses

The following IP ranges will not be available via the Internet:

10.0.0.0 - 10.255.255.255
172.16.0.0 - 172.31.255.255
192.168.0.0 - 192.168.255.255

Also, IP addresses in the range of 169.254.0.0 -169.254.255.255 are reserved for Automatic Private IP Addressing.

If you have a computer on the same network (as in the general home or corporate LAN scenario), you can use a nice graphical browser and the IP Address we determine to run the web install steps, and use Koha afterwards. If you have a hosted site with a fully qualified domain name, you may be able to use that. Otherwise, your scenario requires assistance from your hosting provider or network administrator. Regardless, the instructions as given and written will work to set up Koha.

Determine Address

Determine if there is at least one network card in it. Type the following:

$ sudo ifconfig

This should give output like:

eth0      Link encap:Ethernet  HWaddr 08:00:27:14:22:6c
          inet addr:192.168.69.38  Bcast:192.168.69.255  Mask:255.255.255.0
          inet6 addr: fe80::a00:27ff:fe14:226c/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:24087 errors:0 dropped:0 overruns:0 frame:0
          TX packets:29550 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:2968198 (2.9 MB)  TX bytes:4828089 (4.8 MB)

lo        Link encap:Local Loopback
          inet addr:127.0.0.1  Mask:255.0.0.0
          inet6 addr: ::1/128 Scope:Host
          UP LOOPBACK RUNNING  MTU:16436  Metric:1
          RX packets:11 errors:0 dropped:0 overruns:0 frame:0
          TX packets:11 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0
          RX bytes:3794 (3.7 KB)  TX bytes:3794 (3.7 KB)

In this example, there is "eth0" and "lo". "lo" is not accessible from another machine. "eth0" has an "inet addr" (IP Address) of "192.168.69.38".

If this IP address was not listed in the private IP addresses section above, it may be possible to use it as well. So when the web install steps are reached, instead of installing lynx and using it, Firefox (or any other browser) can be used from another machine by typing "http://" that IP address followed with a ":8080" into the address bar. This is an external address. Attempt external addresses before private ones.

This example has a private IP address: "192.168.69.38". So when the web install steps are reached, instead of installing lynx and using it, Firefox (or any other browser) can be used from another machine on the same network by typing "http://192.168.69.38:8080/" into the address bar. If there is more than one network card (e.g. eth1, eth2, etc.), attempt the IP Addresses in order until you have success or all fail. A typical failure is some sort of "time out" page. If the attempts fail, follow the instructions as written.

Fully Qualified Domain Name

If you are hosted and you happen to know the fully qualified domain name (e.g. library.frammisdoobie.org), you can attempt "http://library.frammisdoobie.org:8080/". If that fails, follow the instructions as written.

Web Installation

You still need to configure/install Koha via the Admin Page. Navigate to: http://127.0.1.1:8080

If you do not know how to do this, try installing lynx:

$ sudo apt-get install lynx
$ lynx http://127.0.1.1:8080

Login with koha user name and password. See the Create User and Grant Permissions section above.

Web Installer Step 1

Choose Language

Use en for English.

Click Next

It will check to make sure all dependencies are installed. You will have to install all items listed here, before you can continue.

It should say: All dependencies installed.

Click Next.

Web Installer Step 2

This shows the Database Settings. All of the entries listed on this page were given to it when you ran the file Makefile.PL.

Click Next

It will check to make sure it can connect to mysql, that the kohadata database exists, and the user koha has all of the required privileges on the database kohadata.

It should say:

Connection established.

Database kohadata exists.

User koha has all required privileges on database kohadata.

Click Next.

Web Installer Step 3

We are now ready to create the database tables and fill them with some default data.

Click Next.

It should say:

Success

*Database tables created

Click Next.

We are ready to do some basic configuration. Please install basic configuration settings to continue the installation.

Click on the link install basic configuration settings.

Select your MARC flavour.

Select Marc21.

Click Next.

Select Default Settings.

(Select everything, if you are testing.)

You may find it helpful to select all of the optional MARC frameworks.

The one option that would be better to leave unchecked and to setup yourself in Koha is (sample_libraries). It adds about 10 sample libraries to koha. It is easy to enter your Library’s information in Koha and you will need to do that anyway.

Click Import.

It shows a list of items added and will report any errors here as well.

Click Finish.

Congratulations , Setup Complete.

Your page will be redirected ot the login page after completing installation.

Setup Your Library in Koha

After the web install, you should be redirected to: http://127.0.1.1:8080

Login with koha user name and password.

Click on the More dropdown menu.

Select Administration.

Select Libraries, branches and groups under the “Basic Parameters” heading.

Click New Library and enter your information into the form.

Click Submit.

Your Library is now setup in Koha.

Base Install Finished

The staff client, or administrative page, can be accessed at:

http://127.0.1.1:8080

The OPAC, or client page, can be accessed at:

http://127.0.1.1

You should now have a functional Koha Installation

Upgrade Instructions

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.

In order to upgrade, find the path to the koha install-log file:

$ sudo find / -name 'koha-install-log'

For a standard install, it should be somewhere under /usr/share/koha. Otherwise, it should be somewhere under /home.

When upgrading from a previous installation of Koha 3, you can use the following from your current build directory:

$ perl Makefile.PL --prev-install-log /path/to/koha-install-log
$ make
$ make test
$ sudo make upgrade

Koha 3.4.x or later no longer stores items in biblio records. If you are upgrading from a version older than Koha 3.4.x, run the following two commands which can take a long time (several hours) to complete for large databases:

$ ./misc/maintenance/remove_items_from_biblioitems.pl --run
$ su -c "misc/migration_tools/rebuild_zebra.pl -b -a -r -v" koha

Uninstall Instructions

Remove Koha Apache Files

# sudo a2dissite koha
# sudo rm /etc/apache2/sites-available/koha
# sudo /etc/init.d/apache2 restart

Disable and Remove Zebra Daemons

# sudo update-rc.d koha-zebra-daemon remove
# sudo rm /etc/init.d/koha-zebra-daemon
# sudo update-rc.d koha-zebraqueue-daemon remove
# sudo rm /etc/init.d/koha-zebraqueue-daemon

Remove MySQL Database

# mysql -u koha -p
> drop database kohadata;

Remove Zebra Indexes

Remove them for both biblios and authorities:

$ sudo zebraidx -c /etc/koha/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
$ sudo zebraidx -c /etc/koha/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init

Remove Install Directories and Configuration Files

DISCLAIMER: The Command rm -r is an extremely powerful deletion tool. It will irrevocably remove what you tell it to. Use With Caution.

Crontab Entries

$ sudo rm -r /etc/cron.d/koha

Install Directories and Configuration Files

These correspond to the directories listed earlier:

$ sudo rm -r /usr/share/koha 
$ sudo rm -r /etc/koha 
$ sudo rm -r /var/log/koha 
$ sudo rm -r /var/lib/koha 
$ sudo rm -r /var/lock/koha 
$ sudo rm -r /var/run/koha

Koha on ubuntu - tarball

Introduction

Pre-Installation Setup

Notation

Install Ubuntu

Add A Koha Community Repository

Update Ubuntu

Add 'koha' User

Configuring the Character Set (Part 1)

Installation Method

Download the latest Koha release

Install Dependencies

Determine Build Directory

Ubuntu Packages from Repository

Ubuntu Packages for Perl Dependencies

Perl dependencies via Unmarked Ubuntu Repositories

Perl dependencies via CPAN

Create MySQL Database and Grant Privileges

Update 'root' MySQL Password

Create MySQL Database

Create User and Grant Permissions

Test to make sure the SAX Parser is setup correctly

Configure Koha

Type of Install

Installation Directory

User Account

Database Engine

Database and Access Account

Zebra Settings

Zebra Database Access

Miscellaneous

Configuration Output

Build, Test, and Install Koha

Pre-Web Install Setup

Ubuntu MySQL Security Tweak

Configuring the Character Set (Part 2)

Apache

MySQL

Tweaking my.cnf

Configure System Wide Environment Variables

Configure and Start Apache

Place Koha Site File

Tweak Koha Site File

Setup Default Ports

Disable or Edit Default Site

Enable Modules and Site

Setup Zebra

Server to Start on Boot Up

Configure Zebra Indexing

Determining an IP Address

Assumptions

Private IP Addresses

Determine Address

Fully Qualified Domain Name

Web Installation

Web Installer Step 1

Web Installer Step 2

Web Installer Step 3

Setup Your Library in Koha

Base Install Finished

Upgrade Instructions

Uninstall Instructions

Remove Koha Apache Files

Disable and Remove Zebra Daemons

Remove MySQL Database

Remove Zebra Indexes

Remove Install Directories and Configuration Files

Crontab Entries

Install Directories and Configuration Files

Navigation menu

Search