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