Bug 8215: Followup FIX QA issues
[koha.git] / INSTALL.ubuntu.12.04
1 =================================================================
2 Installation Guide for Installing Koha
3 on Ubuntu Precise Pangolin (12.04 LTS) with MySQL 5.5
4 =================================================================
5
6 Copyright (C) 2007, 2008 LibLime (http://liblime.com)
7 Some parts copyright 2010 Chris Nighswonger
8 Some parts copyright 2012 Tomas Cohen Arazi
9 Some parts copyright 2012 Mark Tompsett
10
11 Original author: Joshua Ferraro
12 Modified for Ubuntu by: Chris Nighswonger
13                         (cnighswonger AT foundations DOT edu)
14
15 More updates by: Tomas Cohen Arazi (tomascohen AT gmail DOT com)
16                  Mark Tompsett (mtompset AT hotmail DOT com)
17
18 Feedback/bug reports: Koha Developer's List:
19 http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
20
21 This document last modified: 24 July 2012
22
23 Installation Instructions
24 =================================================================
25
26 Running commands can mostly be performed as a system user with
27 sudo privileges, however some need to be run directly as root.
28
29 1. Prepare System and Install Dependencies
30
31 1.1 Install Ubuntu 12.04 LTS via CD/DVD/USB
32
33   Download and install Ubuntu from the official site.
34     - Server edition (command-line only)
35         http://www.ubuntu.com/download/server
36     - Desktop edition
37         http://www.ubuntu.com/download/desktop
38   To keep your Koha installation minimal and to free resources
39   for running, the Server edition is recommended, though the
40   Desktop edition will work as well.
41
42   As Apache and MySQL will be installed in the instructions
43   later, there is no need to select any packages during the
44   installation of Ubuntu.
45
46 1.2 Add koha repository to your apt sources
47
48   NOTE: This is not required for koha 3.6.7 under Ubuntu 12.04
49         if Zebra indexing (see step 5.2) is done via cron jobs.
50   NOTE: 3.8.x is the recommended current stable release to use.
51
52   There are currently three active repositories: oldstable,
53   squeeze, and squeeze-dev. As of 2012-07-24, they represent
54   3.6.x, 3.8.x, and master respectively. This will change when
55   3.10.x is released. They will represent 3.8.x, 3.10.x, and
56   master respectively.
57
58   It is recommended to use squeeze at this time, as 3.8.x is the
59   current stable release.
60
61   Run these commands:
62     $ echo "deb http://debian.koha-community.org/koha squeeze main" | sudo tee /etc/apt/sources.list.d/koha-community.list
63     $ wget -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -
64     $ sudo apt-get update ; sudo apt-get upgrade
65
66 1.3 Install Apache2 and MySQL 5.5
67
68   Install the Apache2 server:
69     $ sudo apt-get install apache2
70
71   If your MySQL server will be on your Koha server, or this
72   instruction is confusing:
73     $ sudo apt-get install mysql-server
74
75   NOTE: You will be prompted to set your root password for MySQL.
76
77 1.4 Set up your locale
78
79   Your locale should be set to UTF-8, as should Apache2 and
80   MySQL 5.5. This step is VERY IMPORTANT for a UNICODE compliant
81   system. You _MUST_ be sure to set this BEFORE you install Koha.
82
83 1.4.1 Ubuntu Locale
84
85   Verify you have a UTF-8 locale in use:
86     $ locale
87   You will recognize if it is UTF-8 or not. Ubuntu 12.04 should
88   not generally require any further steps.
89
90   If it is not set to something UTF-8, use:
91     $ locale -a
92
93   You can select one (note that utf8 becomes UTF-8) and use:
94     $ sudo update-locale LANG=en_US.UTF-8
95
96   You have to log out and back in to see locale change reflected
97   in the locale command.
98
99   Verify your system local by running the following command:
100     $ locale
101
102 1.4.2 Apache2 and MySQL Locales
103   Please read over the following document carefully for more
104   information:
105     http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Configuring_the_Character_Set
106
107 1.5 Get Koha
108
109   There are two ways to install Koha. The easy way is using Debian/Ubuntu
110   packages (check http://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages
111   for further instructions).
112
113   The other way is installing from sources. You can get Koha's source
114   either using git (see 1.5.1) or downloading the stable release tarball.
115
116   1.5.1 Download from Git
117
118   Install Git:
119     $ sudo apt-get install git
120
121   Download Koha (the 3.10.x branch):
122     $ git clone git://git.koha-community.org/koha.git kohaclone
123     $ cd kohaclone
124     $ git checkout -b myinstall origin/3.10.x
125
126   NOTE: for more information about Git, please see the Koha Git
127         Usage Guide:
128    http://wiki.koha-community.org/wiki/Version_Control_Using_Git
129
130   1.5.2 Download from Tarball
131
132   You can get the sources from
133    http://download.koha-community.org. Issuing the following
134   command you can get the latest stable release (recommended):
135
136   Download and Unpack Koha:
137     $ wget http://download.koha-community.org/koha-latest.tar.gz
138     $ tar xvf koha-latest.tar.gz
139
140   Determine the version and change directory:
141     $ ls
142     koha-3.10.00  koha-latest.tar.gz
143     $ cd koha-3.10.00
144
145
146 1.6 Install additional Ubuntu dependencies
147
148   Several Koha dependencies have been conveniently packaged and
149   will be installed issuing the following command:
150
151     $ sudo apt-get install `cat install_misc/ubuntu.12.04.packages | \
152             cut -f1 | grep -v '#' | grep -v -e '^$'`
153
154   Confirm that you want to install the required packages when prompted,
155
156 1.7 Install Perl dependencies that aren't packaged
157
158 ****************************************************************
159   IMPORTANT:  You should only use CPAN for Perl dependencies
160               which are NOT available from the package
161               maintainer. You have been warned!
162 ****************************************************************
163
164   Run the test script to identify missing libraries
165     $ ./koha_perl_deps.pl -m -u
166
167   If there are any dependencies which are missing or need
168   upgrading, first attempt aptitude searches:
169     $ aptitude search libbusiness-isdn-perl
170
171   Notice how the name transformed to 'lib' plus the lowercase
172   library name using '-'s instead of '::'s plus '-perl'. This
173   will generally help find what is missing. And then a simple
174   apt-get install can be done:
175     $ sudo apt-get install libbusiness-isdn-perl
176
177   Do this for all the dependencies listed. Then re-run the
178   command:
179     $ ./koha_perl_deps.pl -m -u
180
181   In general, the repositories on debian.koha-community.org
182   should have any missing pieces. The list should be empty.
183
184   If any are still listed, they can be installed using the 'cpan'
185   command. If and only if you are unable to find any of the
186   dependencies should you use the cpan command. For example:
187     $ sudo cpan GD GD::Barcode::UPCE Algorithm::CheckDigits
188
189   NOTE: you may need to run CPAN initialization if you've not run
190         cpan before:
191 --------
192     /etc/perl/CPAN/Config.pm initialized.
193
194     CPAN is the world-wide archive of perl resources. It consists of about
195     100 sites that all replicate the same contents all around the globe.
196     Many countries have at least one CPAN site already. The resources
197     found on CPAN are easily accessible with the CPAN.pm module. If you
198     want to use CPAN.pm, you have to configure it properly.
199
200     If you do not want to enter a dialog now, you can answer 'no' to this
201     question and I'll try to autoconfigure. (Note: you can revisit this
202     dialog anytime later by typing 'o conf init' at the cpan prompt.)
203
204     Are you ready for manual configuration? [yes]
205 --------
206   When the configuration is completed CPAN will install the Perl
207   modules passed on the command-line.
208
209   For further explanation and reading see:
210      http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Ubuntu_Packages_for_Perl_Dependencies
211
212
213 2. Configuration of dependencies
214
215 2.1 Update root MySQL password
216
217   If during the installation of MySQL you were not prompted to
218   set the MySQL password:
219     $ sudo mysqladmin password <password>
220
221 2.2 Create the Koha database
222
223   Create the database and user with associated privileges. To do
224   this, decide on the koha database name, the koha user name, and
225   the koha user password. Substitute these into the following
226   commands:
227     $ mysql -u root -p
228     Enter mysql root password:
229     Welcome to the MySQL monitor.  Commands end with ; or \g.
230     Your MySQL connection id is 42
231     Server version: 5.5.24-0ubuntu0.12.04.1 (Ubuntu)
232
233     Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.
234
235     Oracle is a registered trademark of Oracle Corporation and/or its
236     affiliates. Other names may be trademarks of their respective
237     owners.
238
239     Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
240
241     mysql> CREATE DATABASE {kohadatabasename};
242     mysql> SHOW DATABASES;
243     mysql> CREATE user '{kohauserbasename}'@'localhost' IDENTIFIED by '{kohauserpassword}';
244     mysql> GRANT ALL ON {kohadatabasename}.* TO '{kohausername}'@'localhost' IDENTIFIED BY '{kohauserpassword}';
245     mysql> USE mysql;
246     mysql> SELECT host,user FROM user;
247     mysql> DELETE FROM user WHERE user='';
248     mysql> SELECT host,user FROM user;
249     mysql> FLUSH PRIVILEGES;
250     mysql> QUIT
251
252   For further explanation of these commands see:
253     http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Create_MySQL_Database_and_Grant_Privileges
254
255
256 2.3 Test your SAX Parser and correct where necessary
257
258   You must be sure you're using the XML::LibXML SAX parser, not
259   Expat or PurePerl, both of which have outstanding bugs with
260   pre-composed characters. Test your SAX parser by running:
261     $ ./misc/sax_parser_print.pl
262
263   If your setup is wrong, the script will output something like:
264     Koha wants something like:
265       XML::LibXML::SAX::Parser=HASH(0x81fe220)
266     You have:
267       XML::SAX::Expat=HASH(0x1a94e88)
268     Looks bad, check INSTALL.* documentation.
269
270   It means you are using Expat (it could also say PurePerl).
271   You'll need to edit your ini file, located at:
272     /etc/perl/XML/SAX/ParserDetails.ini
273
274   Move the entire section for '[XML::LibXML::SAX::Parser]' to the
275   bottom of the ini file. Then run the script again. The output
276   should look like this:
277     $ misc/sax_parser_print.pl
278     Koha wants something like:
279       XML::LibXML::SAX::Parser=HASH(0x81fe220)
280     You have:
281       XML::LibXML::SAX::Parser=HASH(0x16dfee8)
282     Looks good.
283
284   For further details see:
285     http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Test_to_make_sure_the_SAX_Parser_is_setup_correctly
286
287
288 3. Run the Koha installer
289
290   Add a user for installing koha and running zebra:
291     $ sudo adduser koha
292
293   Build and install Koha:
294     $ perl Makefile.PL
295     ( answer questions )
296     $ make
297     $ make test
298     $ sudo make install
299
300
301 4. Configure and start Apache
302
303   This will help make koha available to be a website:
304    $ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha
305
306   NOTE: the path to koha-httpd.conf may be different depending on
307         your installation choices.
308
309   Make sure you have this lines in /etc/apache2/ports.conf:
310     Listen 80
311     Listen 8080
312   Add the missing one.
313
314   The default installation of Koha does not use named virtual
315   hosts. If you will not be running named virtual hosts, comment
316   out the following line:
317     NameVirtualHost *:80
318
319   Run the following commands:
320     $ sudo a2enmod rewrite deflate
321     $ sudo a2ensite koha
322     $ sudo apache2ctl restart
323
324   Note: you may still see the usual Apache default site if your
325         VirtualHost configuration isn't correct.  The command
326         "sudo a2dissite default" may be a quick fix, but may have
327         side-effects.  See the Apache HTTPD manual section on
328         virtual hosts for full instructions.
329
330
331 5. Configure and start Zebra
332
333   This process send responses to search requests sent by Koha or
334   Z39.50/SRU/SRW clients.
335
336   NOTE: the user you run Zebra as will be the only user with
337         write permission on the Zebra index; in development mode,
338         you may wish to use your system user.
339
340
341 5.1 Zebra Search Server
342
343   Set the zebra daemon to run on start:
344     $ sudo ln -s /usr/share/koha/bin/koha-zebra-ctl.sh /etc/init.d/koha-zebra-daemon
345     $ sudo update-rc.d koha-zebra-daemon defaults
346     $ sudo /etc/init.d/koha-zebra-daemon start
347
348   NOTE: change the path to koha-zebra-ctl.sh to match your setup
349         if not using the default.
350
351
352 5.2 Zebra Indexer
353
354   There are two ways to do this. ONLY DO ONE! DO NOT DO BOTH!
355
356   Option 1:
357     You can configure zebra-indexing as an background daemon, see
358       http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra
359
360   Option 2:
361
362     Add an entry in Koha user crontab to scheduled
363     added/updated/deleted records indexing by Zebra with this
364     command:
365       <path/to/koha>/misc/migration_tools/rebuild_zebra -z -b -a
366
367     See check misc/cronjobs/crontab.example for usage examples.
368
369     NOTE: This job should be setup under the kohauser
370           (the default is 'koha').
371
372
373 6. Run the Web Installer, populate the database,
374    initial configuration of settings
375
376   The hope is that your server is accessible via a nice browser
377   somewhere. If not, install lynx to finish the web install on
378   your Koha server:
379     $ sudo apt-get install lynx
380
381   Point your browser to http://<servername>:8080/
382
383   If you installed lynx, and are using defaults, it might be
384   something like:
385     $ lynx http://127.0.1.1:8080/
386
387   It should redirect you to the Web Installer where you can
388   continue the setup. You can install the sample data for
389   libraries, patrons, etc. via the Web Installer
390
391
392 7. Install additional languages
393
394   In your install directory you can run this commands to have
395   your Koha setup translated to your language:
396
397   Set your environment variables:
398     $ export KOHA_CONF=/etc/koha/sites/koha/koha-conf.xml
399     $ export PERL5LIB=/usr/share/koha/lib/
400
401   NOTE: the path to koha-conf.xml may be different depending on
402         your installation choices.
403
404   Run the translator script:
405     $ cd /usr/share/koha/misc/translator
406     $ perl translate install <language-code>
407
408   <language-code> must be one of the included in the
409   misc/translator/po directory.
410
411   NOTE: You can add as many languages as you need. In order to
412         use them you will have to enable them first in the
413         'I18N/L10N' section of the Koha preferences.
414
415
416 8. What next?
417
418   NOTE: You can use the 'Stage MARC records for import' from the
419         Tools area of Koha's Staff Client to import a batch of
420         MARC records, rather than these instructions.
421
422   Once the installer has completed, you can import and index MARC
423   records from the command line thusly:
424     $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml
425   NOTE: use the correct path to your koha-conf.xml
426
427 8.1 Import
428
429   Bibliographic data in MARC21 format:
430     $ misc/migration_tools/bulkmarcimport.pl -file /path/to/marc.iso2709
431
432   Authority data in MARC21 format:
433     $ misc/migration_tools/bulkauthimport.pl -file /path/to/auth.iso2709
434
435 8.2 Fast Index:
436
437   NOTE: This script must be run as the kohauser otherwise
438         permission errors and indexing problems will follow.
439         (the default is 'koha' -- see step 3).
440
441     $ misc/migration_tools/rebuild_zebra.pl -b -w
442
443   Once the indexing has completed, you will be able to search for
444   records in your system.
445
446
447 8.3 Public Z39.50/SRU server
448
449   To enable public Z39.50/SRU servers, you'll need to edit your
450   koha-conf.xml and change the <listen> options to listen on a
451   TCP port; then restart the zebra daemon.
452
453
454 UPGRADE
455 =================================================================
456
457   If you are running in another language other than English,
458   please switch to English before doing the upgrade, the
459   templating system has changed and the templates will need to be
460   regenerated.
461
462   Once you have upgraded, please regenerate your templates in
463   your chosen languages.
464
465
466 1. Install new Perl dependencies
467
468   If you are upgrading from a previous installation of Koha 3.x,
469   you can use the following to identify new Perl dependencies:
470     $ ./koha_perl_deps.pl -u -m
471
472   Install any missing modules using the instructions on sections
473   1.6 and 1.7.
474
475
476 2. Upgrade Koha
477
478     $ perl Makefile.PL --prev-install-log /path/to/koha-install-log
479     $ make
480     $ make test
481     $ sudo make upgrade
482
483
484 3. Pre-3.4 upgrades
485
486   Koha 3.4.x or later no longer stores items in biblio records so
487   if you are upgrading from an older version as part of the
488   upgrade you will need to do the following two steps, they can
489   take a long time (several hours) to complete for large
490   databases:
491     $ misc/maintenance/remove_items_from_biblioitems.pl --run
492     $ misc/migration_tools/rebuild_zebra.pl -b -r
493
494
495 Uninstall Instructions
496 =================================================================
497
498 1. Stop Services:
499
500   Firstly, remove the apache website:
501     $ sudo a2dissite koha
502     $ sudo rm /etc/apache2/sites-available/koha
503     $ sudo apache2ctl restart
504
505   Next, remove the koha-zebra-daemon:
506     $ sudo update-rc.d koha-zebra-daemon remove
507     $ sudo rm /etc/init.d/koha-zebra-daemon
508
509
510 2a. Remove Database:
511
512   Remember the <kohauser>, <kohapassword, and <kohadatabasename>
513   need to be substituted on the following commands:
514    $ mysql -u<kohauser> -p<kohapassword>
515    mysql> drop database <kohadatabasename>;
516
517
518 2b. Remove Indexes:
519
520   To help determine what <prefix> should be substituted with,
521   run the following command:
522     $ sudo find / -name "zebra-biblios.cfg"
523     /etc/koha/zebradb/zebra-biblios.cfg
524     /home/user/koha-3.08.03/etc/zebradb/zebra-biblios.cfg
525     /home/user/koha-3.08.03/blib/ZEBRA_CONF_DIR/zebra-biblios.cfg
526   There may be three copies, two of which will likely be in the
527   user account that installed Koha. In this example, our <prefix>
528   is '/etc/koha'.
529
530   Once you know the value of prefix, run these commands
531   substituting in the correct value:
532    $ zebraidx -c <prefix>/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
533    $ zebraidx -c <prefix>/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
534
535
536 3. Remove Koha Install Directories and Configuration Files
537    Don't forget about any crontab entries
538
539
540 Tested on the following operating environments
541 =================================================================
542   - Ubuntu Precise Pangolin 12.04
543
544
545 Installer Bug reports
546 =================================================================
547   Please log any installer bug reports at
548   http://bugs.koha-community.org
549
550
551 Other Notes
552 =================================================================
553 This file is part of Koha
554
555 Koha is free software; you can redistribute it and/or modify it
556 under the terms of the GNU General Public License as published by
557 the Free Software Foundation; either version 2 of the License, or
558 (at your option) any later version.
559
560 Koha is distributed in the hope that it will be useful, but
561 WITHOUT ANY WARRANTY; without even the implied warranty of
562 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
563 GNU General Public License for more details.
564
565 You should have received a copy of the GNU General Public License
566 along with Koha; if not, write to the Free Software Foundation:
567     Free Software Foundation
568     51 Franklin Street, Fifth Floor
569     Boston, MA 02110-1301
570     USA
571 Or visit their website: http://www.fsf.org/