Bug 11284: Packaging updates for master branch
[koha.git] / INSTALL.ubuntu
blob60f5ed456c30e4cec3acb678ceec713924172c3d
1 =================================================================
2 Instructions for Installing Koha from Source
3 =================================================================
5 BUG REPORTS AND FEEDBACK
6 =================================================================
8 This document last modified: 18 September 2013
10 Given the nature of documentation to become outdated, or have
11 problems, please either submit feedback or bug reports.
13 Bug reports can be posted at http://bugs.koha-community.org
15 Feedback can be posted on the Koha Developer's List:
16 http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
19 INTRODUCTION
20 =================================================================
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.
27 'nano' is a generic text editor. Please feel free to substitute
28 your favourite editor (vi, emacs, or etc.).
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.
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
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.
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.
48 NOTATION
49 =================================================================
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.
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.
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.
66 INSTALL UBUNTU
67 =================================================================
69 These instructions assume that you have already installed Ubuntu
70 from the official site: http://www.ubuntu.com/download/server
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.
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.
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.
87 ADD A KOHA COMMUNITY REPOSITORY
88 =================================================================
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.
94 To avoid getting prompted for a password in the middle of a
95 chain of commands type the following:
96     sudo ls
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
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
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.
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 -
120 UPDATE UBUNTU
121 =================================================================
123 This process, particularly the upgrade step, may take a while.
125     sudo apt-get update
127     sudo apt-get upgrade
129     sudo apt-get clean
132 DOWNLOAD THE LATEST KOHA RELEASE
133 =================================================================
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.
139 IF YOU ARE DOING A STANDARD INSTALLATION:
140 Downloading Source Via Tarball
141 =================================================================
143     wget http://download.koha-community.org/koha-latest.tar.gz
144     tar xvf koha-latest.tar.gz
145     ls
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.
150 IF YOU ARE DOING A DEV INSTALLATION:
151 Downloading Source Via Git
152 =================================================================
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
159 INSTALL DEPENDENCIES
160 =================================================================
162 Dependencies from Repository
163 =================================================================
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
169 Check For Missing Dependencies
170 =================================================================
172 Check everything was installed, by running the test script to
173 identifty missing libraries:
174     ./koha_perl_deps.pl -m -u
176 Install any required libraries that are missing. It is a good
177 idea to install optional ones that are easily found as well.
180 CREATE MYSQL DATABASE AND GRANT PRIVILEGES
181 =================================================================
183 Create MySQL Database
184 =================================================================
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
190     mysql -u root -p
192     CREATE DATABASE kohadata;
194 The Koha database has now been created with the name kohadata.
196 Create User and Grant Permissions
197 =================================================================
199 Continue entering MySQL commands. SUBSTITUTE A PASSWORD OF YOUR
200 CHOICE FOR THE {PASSWORD}'S IN THE FOLLOWING COMMANDS:
202     CREATE user 'koha'@'localhost' IDENTIFIED by '{PASSWORD}';
203     GRANT ALL ON kohadata.* TO 'koha'@'localhost' IDENTIFIED BY '{PASSWORD}';
204     FLUSH PRIVILEGES;
205     QUIT
207 The Koha administrative user has now been created with the name
208 'koha' and the password of your choosing.
211 CONFIGURE KOHA
212 =================================================================
214 User/Group Environment Variables
215 =================================================================
217 IF YOU ARE DOING A STANDARD INSTALLATION, then create a
218 separate 'koha' system user:
219     sudo adduser koha
221 There is no need to set the following environment variables,
222 because 'koha' is the default account to use.
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
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.
236 Configure Your Koha Install
237 =================================================================
239     perl Makefile.PL
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.
246 Answering the resulting questions requires thinking. Here are
247 some hints.
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.
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.
257 Use the same username and password for the Zebra questions.
259 Don't worry about warnings generated by optional components.
262 Build And Test Koha
263 =================================================================
265 Having configured Koha, build it using the following command:
266     make
268 Once this has successfully run, test Koha using the following
269 command:
270     make test
272 Don't worry about the large number of scary warning scrolling
273 by. All that matters is "PASS" or "FAIL".
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.
282 Install Koha
283 =================================================================
285 Once the make test has successfully run, install Koha.
287 IF YOU ARE DOING A STANDARD INSTALLATION, using the
288 following command (follow any on screen prompts):
289     sudo make install
291 Once this has successfully run, Koha is almost installed. There
292 are only a few more steps left.
294 IF YOU ARE DOING A DEV INSTALLATION, using the
295 following command (follow any on screen prompts):
296     make install
298 No sudo is required as you have access to the directories
299 listed above.
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.
307 PRE-WEB INSTALL SETUP
308 =================================================================
310 Ubuntu MySQL Security Tweak
311 =================================================================
313 There is a security risk in Ubuntu's MySQL default setup. Type
314 the following commands:
315     mysql -u root -p
317     USE mysql;
318     DELETE FROM user WHERE user='';
319     FLUSH PRIVILEGES;
320     QUIT
322 The anonymous connections are now removed.
325 Configure System Wide Environment Variables
326 =================================================================
328 Running scripts and cron jobs requires environment variables set.
329 Use the following commands:
330     sudo nano /etc/environment
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!
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
349     logout
351 You need to logout and back in in order to get the environment
352 variables values to be recognized.
355 CONFIGURE AND START APACHE
356 =================================================================
358 Place Koha Site File
359 =================================================================
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
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
370 Tweak Koha Site File
371 =================================================================
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
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
392 Setup Default Ports
393 =================================================================
395     sudo nano /etc/apache2/ports.conf
397 /etc/apache2/ports.conf must have two lines exactly like
398 the following.  Do not add them if they are already there.
400 FILE PARTIAL (CONFIRM/ADD/CHANGE): /etc/apache2/ports.conf
401 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
402 Listen 80
403 Listen 8080
404 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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.
410 FILE PARTIAL (CONFIRM/ADD/CHANGE): /etc/apache2/ports.conf
411 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
412 #NameVirtualHost *:80
413 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
415 Disable Default Site
416 =================================================================
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
424 Enable Modules and Site
425 =================================================================
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
435 SETUP ZEBRA
436 =================================================================
438 The Zebra process send responses to search requests sent by Koha
439 or Z39.50/SRU/SRW clients.
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.
446 Start Zebra Server on Boot
447 =================================================================
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
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
457 FOR EITHER INSTALLATION:
458     sudo update-rc.d koha-zebra-daemon defaults
459     sudo service koha-zebra-daemon start
461 Configuring Zebra Indexing
462 =================================================================
464 IF YOU ARE DOING A STANDARD INSTALLATION, use this command:
465     sudo nano /etc/cron.d/koha
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
474 IF YOU ARE DOING A DEV INSTALLATION, use this command:
475     crontab -e
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
485 SETUP ADDITIONAL LANGUAGES
486 =================================================================
488 To use multi-lingual sample data, please install languages
489 which may be useful for use in the Koha system.
491 Information on this can be found:
492 http://wiki.koha-community.org/wiki/Installation_of_additional_languages_for_OPAC_and_INTRANET_staff_client
495 WEB INSTALLATION
496 =================================================================
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.
501 The password will be what you set in the 'Create User and
502 Grant Permissions' section above.
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.
509     sudo apt-get install lynx
511     lynx http://127.0.1.1:8080/
514 SET UP YOUR LIBRARY IN KOHA
515 =================================================================
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.
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/
535 USEFUL REFERENCE LINKS
536 =================================================================
538 Documentation:
539 http://koha-community.org/documentation/
541 Additional Languages:
542 http://wiki.koha-community.org/wiki/Installation_of_additional_languages_for_OPAC_and_INTRANET_staff_client
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
548 Frequently Asked Questions:
549 http://koha-community.org/documentation/faq
551 Bug Reports:
552 http://bugs.koha-community.org/
554 Public Z39.50/SRU server:
555 http://wiki.koha-community.org/wiki/Troubleshooting_Koha_as_a_Z39.50_server
557 Alternate Indexing Method:
558 http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra
561 UPGRADING
562 =================================================================
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.
569 Once you have upgraded, please regenerate your templates in
570 your chosen languages.
572 First, ensure the most recent dependencies are installed:
573     sudo apt-get update
574     sudo apt-get install koha-deps koha-perldeps
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'
580 Change directory into the latest koha source directory, and then:
581     perl Makefile.PL --prev-install-log /path/to/koha-install-log
583 NOTE: Make sure to change the /path/to/koha-install-log to the
584 one that was found.
586     make
587     make test
589 And if that passes:
590     sudo make upgrade
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'
596     cd ~/kohaclone
597     perl Makefile.PL --prev-install-log /path/to/koha-install-log
599 NOTE: Make sure to change the /path/to/koha-install-log to the
600 one that was found.
602     make
603     make test
605 And if that passes:
606     make upgrade
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.
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"
620 IF YOU ARE DOING A DEV UPGRADE
621     ./misc/migration_tools/rebuild_zebra.pl -b -a -r -v
624 UNINSTALL INSTRUCTIONS
625 =================================================================
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
635 Remove Database
636 =================================================================
637     mysql -u koha -p
639     drop database kohadata;
640     quit
642 Remove Indexes
643 =================================================================
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
654 You may wish to follow up with:
655     sudo find / -t d -name "koha"
656 to help find any remnants.
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!
670 LICENSE
671 =================================================================
673 This file is part of Koha.
675 Major re-write by Mark Tompsett
676 Copyright (C) 2013
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)
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.
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.
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>.