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