Koha-community/Koha
13
7
Fork 0
Code Issues Releases Wiki Activity
Koha/INSTALL.ubuntu.12.04

578 lines
19 KiB
Text
Raw Blame History

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