These instructions will be tested with Ubuntu 10.04 LTS and Ubuntu 12.04 LTS specifically. We strongly recommend an LTS release, though anything higher than 10.04 should work.
Given that long term support for Ubuntu 8.04 LTS ends shortly and that Koha has included newer libraries, Ubuntu 8.04 LTS is not supported. The highest version that could be installed on Ubuntu 8.04 LTS is Koha 3.4.8, and support for that version of Koha is no longer available. So please, do not attempt to install Koha on anything prior to Ubuntu 10.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 ‘gedit’, feel free to substitute your favourite editor (vi, emacs, etc.).
There are three ways to install Koha: packages, tarball, and git. These instructions focus on the tarball installation, and are in transition. However, the use of packages is the recommended method. Packages effectively have done most of the difficult work listed below. You can read the Debian package instructions for information on how to do that. 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.
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.
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.
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. First, 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.
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 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.
Install several dependencies
$ sudo apt-get install zip unzip apache2 mysql-server dselect
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.
Install the base git installation first:
$ sudo apt-get install git git-email
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.
Sources are available at ` <http://download.koha-community.org>`_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.
A git download should be kohaclone:
$ ls
kohaclone
For a tarball install it may look like:
$ ls
koha-3.08.04 koha-latest.tar.gz
Change directory into your build directory.
The required packages have been listed into files, such as install_misc/ubuntu.packages, to simplify the installation process. If you are using an LTS, there should be specific files for use, such as install_misc/ubuntu.12.04.packages. Adjust the following command accordingly, only ifyou encounter problems.
Type the following:
$ sudo dpkg --set-selections < install_misc/ubuntu.packages
$ sudo dselect
Choose [I]nstall to install the selected packages. Answer any prompts that come up. Be patient. Wait for it to install all the packages. This may take a long time.
Follow this by choosing [C]onfigure, then [R]emove, and finally [Q]uit.
It is recommended to reboot at this time, as the dselect may have upgraded your kernel version. After you reboot, make sure to change directory back into your build directory.
Check everything was installed, by running the test script to identifty 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 search koha-common
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 Business::ISDN is listed as required, then take the name and use it to make a similar aptitude search command:
$ aptitude search libbusiness-isdn-perl
Or perhaps, if YAML is listed as required. The aptitude command would become the following command:
$ aptitude search libyaml-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, if Business::ISDN was missing or needed upgrading:
$ sudo apt-get install libbusiness-isdn-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 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 a faked example of what you might see:
$ ./koha_perl_deps.pl -m -u
Installed Required Module is
Module Name Version Version Required
--------------------------------------------------------------------------------------------
CGI::Session::Driver::memcached 0 * 0.04 No
DBD::SQLite2 0 * 0.33 No
GD 0 * 2.39 No
Graphics::Magick 0 * 1.3.05 No
Gravatar::URL 0 * 1.03 No
Memoize::Memcached 0 * 0.03 No
Net::LDAP 0 * 0.33 No
Net::LDAP::Filter 0 * 0.14 No
Net::Server 0 * 0.97 No
Readonly::XS 0 * 1.02 No
SMS::Send 0 * 0.05 No
Test::Strict 0 * 0.14 No
UNIVERSAL::require 0 * 0.13 No
--------------------------------------------------------------------------------------------
Total modules reported: 13 * Module is missing or requires an upgrade.
This is perfectly okay to not install, because the entire “Required” column is “No”. So, if after all this processing, the items listed are not required, proceed to the next section.
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.
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.
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.
Run the following command:
$ sudo gedit /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
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: Ubuntu.
If your output does not match the above, edit your mysql settings:
$ sudo gedit /etc/mysql/my.cnf
Find the [mysqld] section and add the following lines (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
The init-connect and character_set_client lines may not work and may prevent mysql from restarting depending on the version of MySQL installed. Attempt the following next (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
If your mysql server does not start, attempt the following (Works under MySQL version 5.5.24-0ubuntu0.12.04.1):
character-set-server=utf8
skip-character-set-client-handsake
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 retreival work properly.
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 Create MySQL Database and Grant Privileges 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
If during the installation of MySQL you were not prompted to set the MySQL password:
$ 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.
$ 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.
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}';
The koha administrative user has now been created with the name koha and the password of your choosing.
However, there is a security risk in Ubuntu’s MySQL default set up. Continue typing MySQL commands.
> 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 username and password are now active for the koha database which was created.
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 gedit /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.
These instructions are in transition. As such, a tarball installation continues to be the focus during this interim time.
Issue the following command to configure Koha, and select defaults except as noted:
$ perl Makefile.PL
unable to locate Koha configuration file koha-conf.xml at /home/.../koha-3.08.04/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]
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]
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]
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]
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}
Continuing with defaults 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]
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}
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]
The script will then output what you have answered and write some configuration files.
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'
Writing Makefile for koha
Writing MYMETA.yml
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
Once this has successfully run, Koha is almost installed. There are only a few more steps left.
3 - Setup the environment variables used by Koha scripts
Edit the following file
$ sudo gedit /etc/cron.d/koha
Add the following lines: (In this case the # in front of the line signifies that the line is a comment and should be added to the file.)
Edit the file
$ sudo gedit /etc/bash.bashrc.local
Add the following lines there:
Save and close the file.
4 - Configure and Start Apache
$ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha
Edit the following file: /etc/apache2/ports.conf
$ sudo gedit /etc/apache2/ports.conf
Add these Lines to the ports.conf file:
Listen 80
Listen 8080
If not running named virtual hosts, comment out the NameVirtualHost lines (prepending the # character to the line).
Comment out these lines from the ports.conf file:
#NameVirtualHost *:80
#NameVirtualHost *:8080
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
5 - Setup Zebra Server to Automatically Start on Boot Up
$ 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
5b - Reindexing Choices
Do Either Option#1[OPTION 1 is Highly RECOMMENDED for Koha version 3.06.02]or Option #2 DO NOT DO BOTH.
Option #1: Use the Zebra Index Daemon to manage indexing.
See ` <http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra>`_http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra
Option #2: Add a cronjob to index your zebra database.
$ sudo gedit /etc/cron.d/koha
and add the following:
# The cronjobs
*/5 * * * * koha $KOHAPATH/bin/migration_tools/rebuild_zebra.pl -a -b -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 zebra index at interval.
The Option #2 reindexing instructions will work without variation. 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. As such, if you are not familiar with cron jobs, follow these instructions without varying and it should work.
6 - You still need to configure/install Koha via the Admin Page
(See Appendix B for Web Installer Instructions)
(See Appendix C for instructions and notes on installing Koha to a second machine that is pointing to the same database as a current machine with Koha installed.)
Admin Page:
http://127.0.1.1:8080
Client Page:
http://127.0.1.1
You should now have a functional Koha Installation
**Skip this section, if you do not want to setup Koha to be accessible from your local network.**
Special notes on domain names and accessibility
Edit the file: /etc/apache2/apache2.conf
# sudo gedit /etc/apache2/apache2.conf
Add these two lines to the top of the file:
#Define the server’s name
ServerName “hostname”
Edit the file: /etc/koha/koha-httpd.conf
# sudo gedit /etc/koha/koha-httpd.conf
Change 123.123.123.123 to the IP Address of the machine.
#OPAC Setup
Add 123.123.123.123:80 to the first <virtual host ***** > line
Example Before:
<VirtualHost 127.0.0.1:80>
Example After:
<VirtualHost 127.0.0.1:80 123.123.123.123:80>
#Intranet Setup / Koha Admin Setup
Add 123.123.123.123:8080 to the second <virtual host ***** > line
Example Before:
<VirtualHost 127.0.0.1:8080>
Example After:
<VirtualHost 127.0.0.1:8080 123.123.123.123:8080>
Edit the /etc/hosts file:
# sudo gedit /etc/hosts
You can find your hostname by typing in hostname at the command line.
Add the following Line to the end of the file:
123.123.123.123 hostname
Run the following commands to activate the new configuration.
# sudo mv /var/www/index.html /var/www/index.bak
# sudo ln -s /usr/share/koha/opac/cgi-bin/opac/opac-main.pl /var/www/index.html
# sudo /etc/init.d/apache2 restart
**You will need to restart your computer at the end of the Koha Setup**
You should now be able to access Koha from any Machine on your Local Netowrk
When upgrading from a previous installation of Koha 3, you can use the following:
$ perl Makefile.PL --prev-install-log /path/to/koha-install-log
$ make
$ make test
$ sudo make upgrade
The path to the koha install-log file can be found using the find command:
$ sudo find /usr/share/koha -name 'koha-install-log'
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
$ misc/migration_tools/rebuild_zebra.pl -b -a -r
Step #1 Stop Services:
# sudo a2dissite koha
# sudo rm /etc/apache2/sites-available/koha
# sudo /etc/init.d/apache2 restart
# 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
Step #2 Remove Database and Indexes
MySQL
# mysql -u<kohauser> -p
> drop database kohadata;
Zebra Indexes
# zebraidx -c <prefix>/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
# zebraidx -c <prefix>/etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
Step #3 Remove Install Directories and Configuration Files
BEGIN DISCLAIMER
The Command rm -r is an extremely powerful deletion tool. It will irrevocably remove what you tell it to. Use With Caution.
END DISCLAIMER
Remove Koha Install Directories and Configuration Files
# rm -r /usr/share/koha
# rm -r /etc/koha
# rm –r /var/log/koha
# rm –r /var/lib/koha
# rm –r /var/lock/koha
# rm –r /var/run/koha
Don’t forget about any crontab entries
# rm -r /etc/cron.d/koha
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/password.
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
Navigate to: http://127.0.1.1:8080
Login with koha/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.
You will get the normal Koha Admin login page when going to http://127.0.1.1:8080 the first time on a machine that is connecting to a Koha database that has already been setup. Normally the Web Installer would come up the first time, but there is no need when the database has already been setup.
Koha is smart enough not to nuke an existing Database, if you get a Web Installer page that probably means you did not provide the correct connection information for the MySQL Database.
ALWAYS make a backup of your database, before doing something that could potentially destroy the database.
The Final Step for configuring a Second Machine to use Koha is to rebuild the Zebra Index. That is accomplished by running the rebuild_zebra.pl script. Run this from the koha user account!
$ perl -I /usr/share/koha/lib /usr/share/koha/bin/migration_tools/rebuild_zebra.pl -b -w
(Note that in some fonts the upper case I looks like a lower case l. The –I is a capital i.)