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
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
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.
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.
46 =================================================================
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
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.
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.
64 =================================================================
66 These instructions assume that you have already installed Ubuntu
67 from the official site: http://www.ubuntu.com/download/server
69 There is no need to install extra packages during the Ubuntu
70 installation. Apache2 and MySQL will be installed in the
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.
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.
84 ADD A KOHA COMMUNITY REPOSITORY
85 =================================================================
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.
91 To avoid getting prompted for a password in the middle of a
92 chain of commands type the following:
95 IF YOU ARE DOING A STANDARD (tarball) INSTALL use the following
97 echo deb http://debian.koha-community.org/koha squeeze main \
98 | sudo tee /etc/apt/sources.list.d/koha.list
100 IF YOU ARE DOING A DEV (typically git) INSTALL use the following
102 echo deb http://debian.koha-community.org/koha squeeze-dev main \
103 | sudo tee /etc/apt/sources.list.d/koha.list
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.
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 \
118 =================================================================
120 This process, particularly the upgrade step, may take a while.
129 DOWNLOAD THE LATEST KOHA RELEASE
130 =================================================================
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.
136 IF YOU ARE DOING A STANDARD INSTALLATION:
137 Downloading Source Via Tarball
138 =================================================================
140 wget http://download.koha-community.org/koha-latest.tar.gz
141 tar xvf koha-latest.tar.gz
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.
147 IF YOU ARE DOING A DEV INSTALLATION:
148 Downloading Source Via Git
149 =================================================================
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
157 =================================================================
159 Dependencies from Repository
160 =================================================================
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
166 Check For Missing Dependencies
167 =================================================================
169 Check everything was installed, by running the test script to
170 identifty missing libraries:
171 ./koha_perl_deps.pl -m -u
173 Install any required libraries that are missing. It is a good
174 idea to install optional ones that are easily found as well.
177 CREATE MYSQL DATABASE AND GRANT PRIVILEGES
178 =================================================================
180 Create MySQL Database
181 =================================================================
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
189 CREATE DATABASE kohadata;
191 The koha database has now been created with the name kohadata.
193 Create User and Grant Permissions
194 =================================================================
196 Continue entering MySQL commands. SUBSTITUTE A PASSWORD OF YOUR
197 CHOICE FOR THE {PASSWORD}'S IN THE FOLLOWING COMMANDS:
199 CREATE user 'koha'@'localhost' IDENTIFIED by '{PASSWORD}';
200 GRANT ALL ON kohadata.* TO 'koha'@'localhost' IDENTIFIED BY '{PASSWORD}';
204 The koha administrative user has now been created with the name
205 koha and the password of your choosing.
209 =================================================================
211 User/Group Environment Variables
212 =================================================================
214 IF YOU ARE DOING A STANDARD INSTALLATION, then create a
215 separate koha system user:
218 There is no need to set the following environment variables,
219 because koha is the default account to use.
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
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.
233 Configure Your Koha Install
234 =================================================================
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
243 Answering the resulting questions requires thinking. Here are
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.
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.
254 Use the same username and password for the Zebra questions.
256 Don't worry about warnings generated by optional components.
260 =================================================================
262 Having configured Koha, build it using the following command:
265 Once this has successfully run, test Koha using the following
269 Don't worry about the large number of scary warning scrolling
270 by. All that matters is "PASS" or "FAIL".
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.
280 =================================================================
282 Once the make test has successfully run, install Koha.
284 IF YOU ARE DOING A STANDARD INSTALLATION, using the
285 following command (follow any on screen prompts):
288 Once this has successfully run, Koha is almost installed. There
289 are only a few more steps left.
291 IF YOU ARE DOING A DEV INSTALLATION, using the
292 following command (follow any on screen prompts):
295 No sudo is required as you have access to the directories
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.
304 PRE-WEB INSTALL SETUP
305 =================================================================
307 Ubuntu MySQL Security Tweak
308 =================================================================
310 There is a security risk in Ubuntu's MySQL default set up. Type
311 the following commands:
315 DELETE FROM user WHERE user='';
319 The anonymous connections are now removed.
322 Configure System Wide Environment Variables
323 =================================================================
325 Running scripts and cron jobs requires environment variables set.
326 Use the following commands:
327 sudo nano /etc/environment
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!
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
348 You need to logout and back in in order to get the environment
349 variables values to be recognized.
352 CONFIGURE AND START APACHE
353 =================================================================
356 =================================================================
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
362 IF YOU ARE DOING A STANDARD INSTALLATION, use the following
364 sudo ln -s /etc/koha/koha-httpd.conf \
365 /etc/apache2/sites-available/koha
368 =================================================================
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
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
380 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
387 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
390 =================================================================
392 sudo nano /etc/apache2/ports.conf
394 /etc/apache2/ports.conf must have two lines exactly like
395 the following. Do not add them if they are already there.
397 FILE PARTIAL (CONFIRM/ADD/CHANGE): /etc/apache2/ports.conf
398 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
401 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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.
407 FILE PARTIAL (CONFIRM/ADD/CHANGE): /etc/apache2/ports.conf
408 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
409 #NameVirtualHost *:80
410 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
413 =================================================================
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
421 Enable Modules and Site
422 =================================================================
424 Now enable the apache modules this config needs, enable koha's
425 configuration, and restart apache.
429 sudo service apache2 restart
433 =================================================================
435 The zebra process send responses to search requests sent by Koha
436 or Z39.50/SRU/SRW clients.
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.
443 Start Zebra Server on Boot
444 =================================================================
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
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
454 FOR EITHER INSTALLATION:
455 sudo update-rc.d koha-zebra-daemon defaults
456 sudo service koha-zebra-daemon start
458 Configuring Zebra Indexing
459 =================================================================
461 IF YOU ARE DOING A STANDARD INSTALLATION, use this command:
462 sudo nano /etc/cron.d/koha
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
471 IF YOU ARE DOING A DEV INSTALLATION, use this command:
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
482 SETUP ADDITIONAL LANGUAGES
483 =================================================================
485 To use multi-lingual sample data, please install languages
486 which may be useful for use in the Koha system.
488 Information on this can be found:
489 http://wiki.koha-community.org/wiki/Installation_of_additional_languages_for_OPAC_and_INTRANET_staff_client
493 =================================================================
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.
498 The password will be what you set in the 'Create User and
499 Grant Permissions' section above.
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.
506 sudo apt-get install lynx
508 lynx http://127.0.1.1:8080/
511 SETUP YOUR LIBRARY IN KOHA
512 =================================================================
514 After the web install, you should be redirected to:
515 http://127.0.1.1:8080
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.
524 Your Library is now setup in Koha.
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/
532 USEFUL REFERENCE LINKS
533 =================================================================
536 http://koha-community.org/documentation/
538 Additional Languages:
539 http://wiki.koha-community.org/wiki/Installation_of_additional_languages_for_OPAC_and_INTRANET_staff_client
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
545 Frequently Asked Questions:
546 http://koha-community.org/documentation/faq
549 http://bugs.koha-community.org/
551 Public Z39.50/SRU server:
552 http://wiki.koha-community.org/wiki/Troubleshooting_Koha_as_a_Z39.50_server
554 Alternate Indexing Method:
555 http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra
559 =================================================================
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
566 Once you have upgraded, please regenerate your templates in
567 your chosen languages.
569 First, ensure the most recent dependencies are installed:
571 sudo apt-get install koha-deps koha-perldeps
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'
577 Change directory into the latest koha source directory, and then:
578 perl Makefile.PL --prev-install-log /path/to/koha-install-log
580 NOTE: Make sure to change the /path/to/koha-install-log to the
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'
594 perl Makefile.PL --prev-install-log /path/to/koha-install-log
596 NOTE: Make sure to change the /path/to/koha-install-log to the
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
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"
617 IF YOU ARE DOING A DEV UPGRADE
618 ./misc/migration_tools/rebuild_zebra.pl -b -a -r -v
621 UNINSTALL INSTRUCTIONS
622 =================================================================
625 =================================================================
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
633 =================================================================
636 drop database kohadata;
640 =================================================================
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
651 You may wish to follow up with:
652 sudo find / -t d -name "koha"
653 to help find any remnants.
655 IF DOING A DEV REMOVAL:
656 The following will work, but is very dangerous! Please copy or
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
664 NOTE: Don't forget to remove the crontab entries!
668 =================================================================
670 This file is part of Koha.
672 Major re-write by Mark Tompsett
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)
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.
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.
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>.