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