Bug 12478: reinstate zebra compatibility for auth search
[koha.git] / INSTALL.ubuntu
1 =================================================================
2 Instructions for Installing Koha from Source
3 =================================================================
4
5 BUG REPORTS AND FEEDBACK
6 =================================================================
7
8 This document last modified: 18 September 2013
9
10 Given the nature of documentation to become outdated, or have
11 problems, please either submit feedback or bug reports.
12
13 Bug reports can be posted at http://bugs.koha-community.org
14
15 Feedback can be posted on the Koha Developer's List:
16 http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
17
18
19 INTRODUCTION
20 =================================================================
21
22 These are the instructions for installing Koha from source. They
23 have been tested using Ubuntu 12.04 LTS. The copyright,
24 licensing, and other details have been put at the end, so the
25 installation can be started as soon as possible.
26
27 'nano' is a generic text editor. Please feel free to substitute
28 your favourite editor (vi, emacs, or etc.).
29
30 To install Koha for production, it is recommended that you use
31 packages. Installing from packages is not the same as installing
32 from source. These are not your recommended instructions for
33 production servers.
34
35 For instructions on how to install Koha on Ubuntu from packages, please
36 consult http://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages
37
38 To help assist with the development and improvement of Koha,
39 continue with these instructions and read more about version
40 control using git! See USEFUL REFERENCE LINKS below.
41
42 These instructions are intended for those who are skilled.
43 They can be used to set up a development system. This install
44 may not be as easy or smooth as you wish. This is to be expected
45 when installing from source.
46
47
48 NOTATION
49 =================================================================
50
51 Commands are indented by 4 spaces, and should be relatively obvious
52 as commands. Commands may have blank lines between them to
53 indicate that you should not just copy and paste the entire block
54 of commands.
55
56 File contents will be surrounded by the plus symbols with a
57 "FILE FULL" or "FILE PARTIAL" and the filename above the plus
58 symbols surrounding file contents.
59
60 Koha is released monthly, so keeping documentation up to date
61 is difficult. The convention is to replace the last number with
62 an x. For example, the current version is part of the 3.14.x
63 series and the former stable version is the 3.12.x series.
64
65
66 INSTALL UBUNTU
67 =================================================================
68
69 These instructions assume that you have already installed Ubuntu
70 from the official site: http://www.ubuntu.com/download/server
71
72 There is no need to install extra packages during the Ubuntu
73 installation. Apache2 and MySQL will be installed in the
74 instructions later.
75
76 Installing a mail transfer agent before installing Koha will
77 prevent the installation of nullmailer. Such an installation
78 and configuration of a mail transfer agent is beyond the
79 scope of this document. Consult your system administrator,
80 network administrator, or IT Department for assistance as needed.
81
82 These instructions assume you created a user account with your
83 login credentials and not one called 'koha'. This is to prevent
84 the system user 'koha' from having more permissions than it should.
85
86
87 ADD A KOHA COMMUNITY REPOSITORY
88 =================================================================
89
90 These instructions still function even though the latest version
91 of Debian is wheezy. If the version has changed again, please
92 confirm these instructions on the mailing list or IRC channel.
93
94 To avoid getting prompted for a password in the middle of a
95 chain of commands type the following:
96     sudo ls
97
98 IF YOU ARE DOING A STANDARD (tarball) INSTALL use the following
99 command:
100     echo deb http://debian.koha-community.org/koha squeeze main \
101         | sudo tee /etc/apt/sources.list.d/koha.list
102
103 IF YOU ARE DOING A DEV (typically git) INSTALL use the following
104 command:
105     echo deb http://debian.koha-community.org/koha squeeze-dev main \
106         | sudo tee /etc/apt/sources.list.d/koha.list
107
108 To use the older stable release:
109 echo deb http://debian.koha-community.org/koha oldstable main \
110 | sudo tee /etc/apt/sources.list.d/koha.list
111 Intentionally not indented, as the others are preferred.
112
113 FOR EITHER INSTALLATION:
114 Add the key in gpg.asc to your APT trusted keys to avoid
115 warning messages on installation:
116     wget -O- http://debian.koha-community.org/koha/gpg.asc \
117         | sudo apt-key add -
118
119
120 UPDATE UBUNTU
121 =================================================================
122
123 This process, particularly the upgrade step, may take a while.
124
125     sudo apt-get update
126
127     sudo apt-get upgrade
128
129     sudo apt-get clean
130
131
132 DOWNLOAD THE LATEST KOHA RELEASE
133 =================================================================
134
135 There are two ways to grab the source, either by using git
136 or by downloading the .tar.gz file. Git is recommended for a
137 development environment.
138
139 IF YOU ARE DOING A STANDARD INSTALLATION:
140 Downloading Source Via Tarball
141 =================================================================
142
143     wget http://download.koha-community.org/koha-latest.tar.gz
144     tar xvf koha-latest.tar.gz
145     ls
146
147 NOTE: You need to cd into the Koha directory, but since the
148 version changes, you'll know by the ls command what it is.
149
150 IF YOU ARE DOING A DEV INSTALLATION:
151 Downloading Source Via Git
152 =================================================================
153
154 Please see the following wiki page and follow the instructions up
155 to and including "git checkout -b mywork origin".
156 http://wiki.koha-community.org/wiki/Version_Control_Using_Git
157
158
159 INSTALL DEPENDENCIES
160 =================================================================
161
162 Dependencies from Repository
163 =================================================================
164
165 The repository added has koha-deps and koha-perldeps packages
166 which make it very easy. Type the following:
167     sudo apt-get install koha-deps koha-perldeps make
168
169 Check For Missing Dependencies
170 =================================================================
171
172 Check everything was installed, by running the test script to
173 identifty missing libraries:
174     ./koha_perl_deps.pl -m -u
175
176 Install any required libraries that are missing. It is a good
177 idea to install optional ones that are easily found as well.
178
179
180 CREATE MYSQL DATABASE AND GRANT PRIVILEGES
181 =================================================================
182
183 Create MySQL Database
184 =================================================================
185
186 If you have difficulty accessing MySQL's root acount, perhaps
187 this Ubuntu page on resetting the root password may help.
188 https://help.ubuntu.com/community/MysqlPasswordReset
189
190     mysql -u root -p
191
192     CREATE DATABASE kohadata;
193
194 The Koha database has now been created with the name kohadata.
195
196 Create User and Grant Permissions
197 =================================================================
198
199 Continue entering MySQL commands. SUBSTITUTE A PASSWORD OF YOUR
200 CHOICE FOR THE {PASSWORD}'S IN THE FOLLOWING COMMANDS:
201
202     CREATE user 'koha'@'localhost' IDENTIFIED by '{PASSWORD}';
203     GRANT ALL ON kohadata.* TO 'koha'@'localhost' IDENTIFIED BY '{PASSWORD}';
204     FLUSH PRIVILEGES;
205     QUIT
206
207 The Koha administrative user has now been created with the name
208 'koha' and the password of your choosing.
209
210
211 CONFIGURE KOHA
212 =================================================================
213
214 User/Group Environment Variables
215 =================================================================
216
217 IF YOU ARE DOING A STANDARD INSTALLATION, then create a
218 separate 'koha' system user:
219     sudo adduser koha
220
221 There is no need to set the following environment variables,
222 because 'koha' is the default account to use.
223
224 IF YOU ARE DOING A DEV INSTALLATION, then create some
225 environment variables for the process to pick up and use later:
226     export __KOHA_USER__=$USER
227     export __KOHA_GROUP__=$USER
228     echo $USER
229
230 The output of the echo command should match your user id,
231 and since the user id and group id are generally the same for
232 a freshly created account, this will make sure the indexing
233 happens as this account.
234
235
236 Configure Your Koha Install
237 =================================================================
238
239     perl Makefile.PL
240
241 How you answer the first question will affect where things will
242 end up being placed. It is recommended that choose 'standard' if
243 you are doing a tarball install, and 'dev' if you are doing a
244 git install.
245
246 Answering the resulting questions requires thinking. Here are
247 some hints.
248
249 Recall that the database created is kohadata set in the Create
250 MySQL Database step. The username and password were set up in
251 the Create User and Grant Permissions step.
252
253 Give some thought should be given to the MARC format desired
254 and the method of character normalization (chr or icu), though
255 the defaults will work as MARC21 just fine.
256
257 Use the same username and password for the Zebra questions.
258
259 Don't worry about warnings generated by optional components.
260
261
262 Build And Test Koha
263 =================================================================
264
265 Having configured Koha, build it using the following command:
266     make
267
268 Once this has successfully run, test Koha using the following
269 command:
270     make test
271
272 Don't worry about the large number of scary warning scrolling
273 by. All that matters is "PASS" or "FAIL".
274
275 If this fails, it is likely due to a failed dependency. Remember,
276 a source installation is not always smooth. You can determine the
277 missing dependency by scrolling back and looking for something
278 like: Can't locate Cache/Memcached/Fast.pm in @INC
279 Install it, and try to build and test again.
280
281
282 Install Koha
283 =================================================================
284
285 Once the make test has successfully run, install Koha.
286
287 IF YOU ARE DOING A STANDARD INSTALLATION, using the
288 following command (follow any on screen prompts):
289     sudo make install
290
291 Once this has successfully run, Koha is almost installed. There
292 are only a few more steps left.
293
294 IF YOU ARE DOING A DEV INSTALLATION, using the
295 following command (follow any on screen prompts):
296     make install
297
298 No sudo is required as you have access to the directories
299 listed above.
300
301 FOR EITHER INSTALLATION:
302 Near the end of this command, the output will have two lines
303 containing KOHA_CONF and PERL5LIB in them.  Take note of the two
304 export commands as you will need them for a later step.
305
306
307 PRE-WEB INSTALL SETUP
308 =================================================================
309
310 Ubuntu MySQL Security Tweak
311 =================================================================
312
313 There is a security risk in Ubuntu's MySQL default setup. Type
314 the following commands:
315     mysql -u root -p
316
317     USE mysql;
318     DELETE FROM user WHERE user='';
319     FLUSH PRIVILEGES;
320     QUIT
321
322 The anonymous connections are now removed.
323
324
325 Configure System Wide Environment Variables
326 =================================================================
327
328 Running scripts and cron jobs requires environment variables set.
329 Use the following commands:
330     sudo nano /etc/environment
331
332 IF YOU ARE DOING A DEV INSTALLATON:
333 FILE PARTIAL (ADD): /etc/environment
334 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
335 KOHA_CONF=/home/{YOUR USER NAME}/koha-dev/etc/koha-conf.xml
336 KOHA_PATH=/home/{YOUR USER NAME}/kohaclone
337 PERL5LIB=/home/{YOUR USER NAME}/kohaclone
338 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
339 NOTE: CHANGE {YOUR USER NAME} TO YOUR ACTUAL USER NAME!
340
341 IF YOU ARE DOING A STANDARD INSTALLATON:
342 FILE PARTIAL (ADD): /etc/environment
343 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
344 KOHA_CONF=/etc/koha/koha-conf.xml
345 KOHA_PATH=/usr/share/koha
346 PERL5LIB=/usr/share/koha/lib
347 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
348
349     logout
350
351 You need to logout and back in in order to get the environment
352 variables values to be recognized.
353
354
355 CONFIGURE AND START APACHE
356 =================================================================
357
358 Place Koha Site File
359 =================================================================
360
361 IF YOU ARE DOING A DEV INSTALLATION, use the following command:
362     sudo ln -s ~/koha-dev/etc/koha-httpd.conf \
363         /etc/apache2/sites-available/koha
364
365 IF YOU ARE DOING A STANDARD INSTALLATION, use the following
366 command:
367     sudo ln -s /etc/koha/koha-httpd.conf \
368         /etc/apache2/sites-available/koha
369
370 Tweak Koha Site File
371 =================================================================
372
373 The default file limits connections to those from 127.0.1.1
374 (or 127.0.0.1), which is rather difficult to test/use in a
375 server environment. Edit the file:
376     sudo nano /etc/apache2/sites-available/koha
377
378 /etc/apache2/sites-available/koha will have a line
379 that should have the IP address changed to a *.
380 FILE PARTIAL (CHANGE): /etc/apache2/sites-available/koha
381 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
382 <VirtualHost *:80>
383 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
384
385 /etc/apache2/sites-available/koha will have another line
386 that should have the IP address changed to a *
387 FILE PARTIAL (CHANGE): /etc/apache2/sites-available/koha
388 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
389 <VirtualHost *:8080>
390 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
391
392 Setup Default Ports
393 =================================================================
394
395     sudo nano /etc/apache2/ports.conf
396
397 /etc/apache2/ports.conf must have two lines exactly like
398 the following.  Do not add them if they are already there.
399
400 FILE PARTIAL (CONFIRM/ADD/CHANGE): /etc/apache2/ports.conf
401 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
402 Listen 80
403 Listen 8080
404 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
405
406 /etc/apache2/ports.conf does not require NameVirtualHost.
407 Do not add it if it is missing or already there. Just
408 prepend # accordingly.
409
410 FILE PARTIAL (CONFIRM/ADD/CHANGE): /etc/apache2/ports.conf
411 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
412 #NameVirtualHost *:80
413 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
414
415 Disable Default Site
416 =================================================================
417
418 These short instructions assume that the default site is
419 not needed.  Talk with your system administrator, network
420 administrator, or IT Department to CONFIRM THIS BEFORE RUNNING
421 the following command:
422     sudo a2dissite 000-default
423
424 Enable Modules and Site
425 =================================================================
426
427 Now enable the Apache modules this config needs, enable Koha's
428 virtual host configuration, and restart Apache.
429     sudo a2enmod rewrite
430     sudo a2enmod deflate
431     sudo a2ensite koha
432     sudo service apache2 restart
433
434
435 SETUP ZEBRA
436 =================================================================
437
438 The Zebra process send responses to search requests sent by Koha
439 or Z39.50/SRU/SRW clients.
440
441 The user you run Zebra as will be the only user with write
442 permission on the Zebra index. For a standard installation, this
443 should be the system user 'koha'. For a dev installation, this
444 should be your system user.
445
446 Start Zebra Server on Boot
447 =================================================================
448
449 IF YOU ARE DOING A STANDARD INSTALLATION, use this command:
450     sudo ln -s /usr/share/koha/bin/koha-zebra-ctl.sh \
451         /etc/init.d/koha-zebra-daemon
452
453 IF YOU ARE DOING A DEV INSTALLATION, use this command:
454     sudo ln -s ~/koha-dev/bin/koha-zebra-ctl.sh \
455         /etc/init.d/koha-zebra-daemon
456
457 FOR EITHER INSTALLATION:
458     sudo update-rc.d koha-zebra-daemon defaults
459     sudo service koha-zebra-daemon start
460
461 Configuring Zebra Indexing
462 =================================================================
463
464 IF YOU ARE DOING A STANDARD INSTALLATION, use this command:
465     sudo nano /etc/cron.d/koha
466
467 FILE FULL: /etc/cron.d/koha
468 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
469 # The cronjobs -- $KOHA_PATH is defined in /etc/environment, and
470 # gets set when this process runs as a user (koha).
471 */5 * * * * koha $KOHA_PATH/bin/migration_tools/rebuild_zebra.pl -b -a -z &> /dev/null
472 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
473
474 IF YOU ARE DOING A DEV INSTALLATION, use this command:
475     crontab -e
476
477 FILE PARTIAL (ADD):
478 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
479 # The cronjobs -- $KOHA_PATH is defined in /etc/environment, and
480 # gets set when this process runs.
481 */5 * * * *     $KOHA_PATH/misc/migration_tools/rebuild_zebra.pl -b -a -z &> /dev/null
482 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
483
484
485 SETUP ADDITIONAL LANGUAGES
486 =================================================================
487
488 To use multi-lingual sample data, please install languages
489 which may be useful for use in the Koha system.
490
491 Information on this can be found:
492 http://wiki.koha-community.org/wiki/Installation_of_additional_languages_for_OPAC_and_INTRANET_staff_client
493
494
495 WEB INSTALLATION
496 =================================================================
497
498 Now you can visit your staff client website to continue with the
499 Koha web installer. The user name to log in with will be koha.
500
501 The password will be what you set in the 'Create User and
502 Grant Permissions' section above.
503
504 Lynx navigational keys include: tab to go between fields, enter
505 (when not on text fields) to toggle or click, space to change
506 pages (when not on text fields), Q to quit (when not on text
507 fields). Arrows also work.
508
509     sudo apt-get install lynx
510
511     lynx http://127.0.1.1:8080/
512
513
514 SET UP YOUR LIBRARY IN KOHA
515 =================================================================
516
517 After the web install, you should be redirected to:
518 http://127.0.1.1:8080
519 Follow these steps:
520 - Login with koha user name and password.
521 - Click on the More dropdown menu.
522 - Select and click Administration.
523 - Click Libraries and groups
524   under the Basic Parameters heading.
525 - Click New Library and enter your information into the form.
526 - Click Submit.
527 Your library is now set up in Koha.
528
529 Take the time to read the documentation to do other necessary
530 setup tasks such as creating a patron, and importing or entering
531 MARC data. The documentation for Koha can be found at:
532 http://koha-community.org/documentation/
533
534
535 USEFUL REFERENCE LINKS
536 =================================================================
537
538 Documentation:
539 http://koha-community.org/documentation/
540
541 Additional Languages:
542 http://wiki.koha-community.org/wiki/Installation_of_additional_languages_for_OPAC_and_INTRANET_staff_client
543
544 Stage MARC Records for Import:
545 http://manual.koha-community.org/3.14/en/catalogtools.html#stagemarc
546 NOTE: The URL has been similar since Koha version 3.8
547
548 Frequently Asked Questions:
549 http://koha-community.org/documentation/faq
550
551 Bug Reports:
552 http://bugs.koha-community.org/
553
554 Public Z39.50/SRU server:
555 http://wiki.koha-community.org/wiki/Troubleshooting_Koha_as_a_Z39.50_server
556
557 Alternate Indexing Method:
558 http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra
559
560
561 UPGRADING
562 =================================================================
563
564 If you are running in another language other than English,
565 please switch to English before doing the upgrade, the
566 templating system has changed and the templates will need to
567 be regenerated.
568
569 Once you have upgraded, please regenerate your templates in
570 your chosen languages.
571
572 First, ensure the most recent dependencies are installed:
573     sudo apt-get update
574     sudo apt-get install koha-deps koha-perldeps
575
576 IF YOU ARE DOING A STANDARD UPGRADE:
577 In order to upgrade, find the path to the koha install-log file:
578     sudo find /usr/share/koha/ -name 'koha-install-log'
579
580 Change directory into the latest koha source directory, and then:
581     perl Makefile.PL --prev-install-log /path/to/koha-install-log
582
583 NOTE: Make sure to change the /path/to/koha-install-log to the
584 one that was found.
585
586     make
587     make test
588
589 And if that passes:
590     sudo make upgrade
591
592 IF YOU ARE DOING A DEV UPGRADE:
593 In order to upgrade, find the path to the koha install-log file:
594     find ~/koha-dev/ -name 'koha-install-log'
595
596     cd ~/kohaclone
597     perl Makefile.PL --prev-install-log /path/to/koha-install-log
598
599 NOTE: Make sure to change the /path/to/koha-install-log to the
600 one that was found.
601
602     make
603     make test
604
605 And if that passes:
606     make upgrade
607
608 FOR EITHER UPGRADE TYPE:
609 If you are upgrading from a version of Koha earlier than 3.4.x,
610 Koha 3.4.x or later no longer stores items in biblio records:
611 ./misc/maintenance/remove_items_from_biblioitems.pl --run
612 Intentionally not indented, in the hopes that most upgrades are
613 post 3.4.x.
614
615 Regardless of version you are upgrading from, a full reindex is
616 always the best option:
617 IF YOU ARE DOING A STANDARD UPGRADE
618     sudo su -l koha --command="/usr/bin/perl /usr/share/koha/bin/migration_tools/rebuild_zebra.pl -b -a -r -v"
619
620 IF YOU ARE DOING A DEV UPGRADE
621     ./misc/migration_tools/rebuild_zebra.pl -b -a -r -v
622
623
624 UNINSTALL INSTRUCTIONS
625 =================================================================
626
627 Stop Services
628 =================================================================
629     sudo a2dissite koha
630     sudo rm /etc/apache2/sites-available/koha
631     sudo service apache2 restart
632     sudo update-rc.d koha-zebra-daemon remove
633     sudo rm /etc/init.d/koha-zebra-daemon
634
635 Remove Database
636 =================================================================
637     mysql -u koha -p
638
639     drop database kohadata;
640     quit
641
642 Remove Indexes
643 =================================================================
644
645 IF DOING A STANDARD REMOVAL:
646     zebraidx -c /etc/koha/zebradb/zebra-biblios.cfg \
647         -g iso2709 -d biblios init
648     zebraidx -c /etc/koha/zebradb/zebra-authorities.cfg \
649         -g iso2709 -d authorities init
650     sudo rm -rf /etc/koha
651     sudo rm -rf /usr/share/koha
652     sudo rm /etc/cron.d/koha
653
654 You may wish to follow up with:
655     sudo find / -t d -name "koha"
656 to help find any remnants.
657
658 IF DOING A DEV REMOVAL:
659 The following will work, but is very dangerous! Please copy or
660 type this correctly.
661     zebraidx -c ~/koha-dev/etc/zebradb/zebra-biblios.cfg \
662         -g iso2709 -d biblios init
663     zebraidx -c ~/koha-dev/etc/zebradb/zebra-authorities.cfg \
664         -g iso2709 -d authorities init
665     rm -rf ~/koha-dev
666     rm -rf ~/kohaclone
667 NOTE: Don't forget to remove the crontab entries!
668
669
670 LICENSE
671 =================================================================
672
673 This file is part of Koha.
674
675 Major re-write by Mark Tompsett
676 Copyright (C) 2013
677
678 Based on remnants by:
679 Copyright (C) 2007, 2008 LibLime (http://liblime.com)
680                           Original author: Joshua Ferraro
681 Some parts Copyright (C) 2010 Chris Nighswonger (modified for ubuntu)
682                           (cnighswonger AT foundations DOT edu)
683 Some parts Copyright (C) 2012 Tomas Cohen Arazi
684                           (tomascohen AT gmail DOT com)
685 Some parts Copyright (C) 2012 Mark Tompsett
686                           (mtompset AT hotmail DOT com)
687
688 Koha is free software; you can redistribute it and/or modify it
689 under the terms of the GNU General Public License as published by
690 the Free Software Foundation; either version 3 of the License, or
691 (at your option) any later version.
692
693 Koha is distributed in the hope that it will be useful, but
694 WITHOUT ANY WARRANTY; without even the implied warranty of
695 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
696 GNU General Public License for more details.
697
698 You should have received a copy of the GNU General Public License
699 along with Koha; if not, see <http://www.gnu.org/licenses>.