================================================================= Instructions for Installing Koha from Source ================================================================= BUG REPORTS AND FEEDBACK ================================================================= This document last modified: 18 September 2013 Given the nature of documentation to become outdated, or have problems, please either submit feedback or bug reports. Bug reports can be posted at http://bugs.koha-community.org Feedback can be posted on the Koha Developer's List: http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel INTRODUCTION ================================================================= These are the instructions for installing Koha from source. They have been tested using Ubuntu 12.04 LTS. The copyright, licensing, and other details have been put at the end, so the installation can be started as soon as possible. 'nano' is a generic text editor. Please feel free to substitute your favourite editor (vi, emacs, or etc.). To install Koha for production, it is recommended that you use packages. Installing from packages is not the same as installing from source. These are not your recommended instructions for production servers. For instructions on how to install Koha on Ubuntu from packages, please consult http://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages To help assist with the development and improvement of Koha, continue with these instructions and read more about version control using git! See USEFUL REFERENCE LINKS below. These instructions are intended for those who are skilled. They can be used to set up a development system. This install may not be as easy or smooth as you wish. This is to be expected when installing from source. NOTATION ================================================================= Commands are indented by 4 spaces, and should be relatively obvious as commands. Commands may have blank lines between them to indicate that you should not just copy and paste the entire block of commands. File contents will be surrounded by the plus symbols with a "FILE FULL" or "FILE PARTIAL" and the filename above the plus symbols surrounding file contents. Koha is released monthly, so keeping documentation up to date is difficult. The convention is to replace the last number with an x. For example, the current version is part of the 3.14.x series and the former stable version is the 3.12.x series. INSTALL UBUNTU ================================================================= These instructions assume that you have already installed Ubuntu from the official site: http://www.ubuntu.com/download/server There is no need to install extra packages during the Ubuntu installation. Apache2 and MySQL will be installed in the instructions later. Installing a mail transfer agent before installing Koha will prevent the installation of nullmailer. Such an installation and configuration of a mail transfer agent is beyond the scope of this document. Consult your system administrator, network administrator, or IT Department for assistance as needed. These instructions assume you created a user account with your login credentials and not one called 'koha'. This is to prevent the system user 'koha' from having more permissions than it should. ADD A KOHA COMMUNITY REPOSITORY ================================================================= These instructions still function even though the latest version of Debian is wheezy. If the version has changed again, please confirm these instructions on the mailing list or IRC channel. To avoid getting prompted for a password in the middle of a chain of commands type the following: sudo ls IF YOU ARE DOING A STANDARD (tarball) INSTALL use the following command: echo deb http://debian.koha-community.org/koha squeeze main \ | sudo tee /etc/apt/sources.list.d/koha.list IF YOU ARE DOING A DEV (typically git) INSTALL use the following command: echo deb http://debian.koha-community.org/koha squeeze-dev main \ | sudo tee /etc/apt/sources.list.d/koha.list To use the older stable release: echo deb http://debian.koha-community.org/koha oldstable main \ | sudo tee /etc/apt/sources.list.d/koha.list Intentionally not indented, as the others are preferred. FOR EITHER INSTALLATION: Add the key in gpg.asc to your APT trusted keys to avoid warning messages on installation: wget -O- http://debian.koha-community.org/koha/gpg.asc \ | sudo apt-key add - UPDATE UBUNTU ================================================================= This process, particularly the upgrade step, may take a while. sudo apt-get update sudo apt-get upgrade sudo apt-get clean DOWNLOAD THE LATEST KOHA RELEASE ================================================================= There are two ways to grab the source, either by using git or by downloading the .tar.gz file. Git is recommended for a development environment. IF YOU ARE DOING A STANDARD INSTALLATION: Downloading Source Via Tarball ================================================================= wget http://download.koha-community.org/koha-latest.tar.gz tar xvf koha-latest.tar.gz ls NOTE: You need to cd into the Koha directory, but since the version changes, you'll know by the ls command what it is. IF YOU ARE DOING A DEV INSTALLATION: Downloading Source Via Git ================================================================= Please see the following wiki page and follow the instructions up to and including "git checkout -b mywork origin". http://wiki.koha-community.org/wiki/Version_Control_Using_Git INSTALL DEPENDENCIES ================================================================= Dependencies from Repository ================================================================= The repository added has koha-deps and koha-perldeps packages which make it very easy. Type the following: sudo apt-get install koha-deps koha-perldeps make Check For Missing Dependencies ================================================================= Check everything was installed, by running the test script to identifty missing libraries: ./koha_perl_deps.pl -m -u Install any required libraries that are missing. It is a good idea to install optional ones that are easily found as well. CREATE MYSQL DATABASE AND GRANT PRIVILEGES ================================================================= Create MySQL Database ================================================================= If you have difficulty accessing MySQL's root acount, perhaps this Ubuntu page on resetting the root password may help. https://help.ubuntu.com/community/MysqlPasswordReset mysql -u root -p CREATE DATABASE kohadata; The Koha database has now been created with the name kohadata. Create User and Grant Permissions ================================================================= Continue entering MySQL commands. SUBSTITUTE A PASSWORD OF YOUR CHOICE FOR THE {PASSWORD}'S IN THE FOLLOWING COMMANDS: CREATE user 'koha'@'localhost' IDENTIFIED by '{PASSWORD}'; GRANT ALL ON kohadata.* TO 'koha'@'localhost' IDENTIFIED BY '{PASSWORD}'; FLUSH PRIVILEGES; QUIT The Koha administrative user has now been created with the name 'koha' and the password of your choosing. CONFIGURE KOHA ================================================================= User/Group Environment Variables ================================================================= IF YOU ARE DOING A STANDARD INSTALLATION, then create a separate 'koha' system user: sudo adduser koha There is no need to set the following environment variables, because 'koha' is the default account to use. IF YOU ARE DOING A DEV INSTALLATION, then create some environment variables for the process to pick up and use later: export __KOHA_USER__=$USER export __KOHA_GROUP__=$USER echo $USER The output of the echo command should match your user id, and since the user id and group id are generally the same for a freshly created account, this will make sure the indexing happens as this account. Configure Your Koha Install ================================================================= perl Makefile.PL How you answer the first question will affect where things will end up being placed. It is recommended that choose 'standard' if you are doing a tarball install, and 'dev' if you are doing a git install. Answering the resulting questions requires thinking. Here are some hints. Recall that the database created is kohadata set in the Create MySQL Database step. The username and password were set up in the Create User and Grant Permissions step. Give some thought should be given to the MARC format desired and the method of character normalization (chr or icu), though the defaults will work as MARC21 just fine. Use the same username and password for the Zebra questions. Don't worry about warnings generated by optional components. Build And Test Koha ================================================================= Having configured Koha, build it using the following command: make Once this has successfully run, test Koha using the following command: make test Don't worry about the large number of scary warning scrolling by. All that matters is "PASS" or "FAIL". If this fails, it is likely due to a failed dependency. Remember, a source installation is not always smooth. You can determine the missing dependency by scrolling back and looking for something like: Can't locate Cache/Memcached/Fast.pm in @INC Install it, and try to build and test again. Install Koha ================================================================= Once the make test has successfully run, install Koha. IF YOU ARE DOING A STANDARD INSTALLATION, using the following command (follow any on screen prompts): sudo make install Once this has successfully run, Koha is almost installed. There are only a few more steps left. IF YOU ARE DOING A DEV INSTALLATION, using the following command (follow any on screen prompts): make install No sudo is required as you have access to the directories listed above. FOR EITHER INSTALLATION: Near the end of this command, the output will have two lines containing KOHA_CONF and PERL5LIB in them. Take note of the two export commands as you will need them for a later step. PRE-WEB INSTALL SETUP ================================================================= Ubuntu MySQL Security Tweak ================================================================= There is a security risk in Ubuntu's MySQL default setup. Type the following commands: mysql -u root -p USE mysql; DELETE FROM user WHERE user=''; FLUSH PRIVILEGES; QUIT The anonymous connections are now removed. Configure System Wide Environment Variables ================================================================= Running scripts and cron jobs requires environment variables set. Use the following commands: sudo nano /etc/environment IF YOU ARE DOING A DEV INSTALLATON: FILE PARTIAL (ADD): /etc/environment +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ KOHA_CONF=/home/{YOUR USER NAME}/koha-dev/etc/koha-conf.xml KOHA_PATH=/home/{YOUR USER NAME}/kohaclone PERL5LIB=/home/{YOUR USER NAME}/kohaclone +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ NOTE: CHANGE {YOUR USER NAME} TO YOUR ACTUAL USER NAME! IF YOU ARE DOING A STANDARD INSTALLATON: FILE PARTIAL (ADD): /etc/environment +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ KOHA_CONF=/etc/koha/koha-conf.xml KOHA_PATH=/usr/share/koha PERL5LIB=/usr/share/koha/lib +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ logout You need to logout and back in in order to get the environment variables values to be recognized. CONFIGURE AND START APACHE ================================================================= Place Koha Site File ================================================================= IF YOU ARE DOING A DEV INSTALLATION, use the following command: sudo ln -s ~/koha-dev/etc/koha-httpd.conf \ /etc/apache2/sites-available/koha IF YOU ARE DOING A STANDARD INSTALLATION, use the following command: sudo ln -s /etc/koha/koha-httpd.conf \ /etc/apache2/sites-available/koha Tweak Koha Site File ================================================================= The default file limits connections to those from 127.0.1.1 (or 127.0.0.1), which is rather difficult to test/use in a server environment. Edit the file: sudo nano /etc/apache2/sites-available/koha /etc/apache2/sites-available/koha will have a line that should have the IP address changed to a *. FILE PARTIAL (CHANGE): /etc/apache2/sites-available/koha +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ /etc/apache2/sites-available/koha will have another line that should have the IP address changed to a * FILE PARTIAL (CHANGE): /etc/apache2/sites-available/koha +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Setup Default Ports ================================================================= sudo nano /etc/apache2/ports.conf /etc/apache2/ports.conf must have two lines exactly like the following. Do not add them if they are already there. FILE PARTIAL (CONFIRM/ADD/CHANGE): /etc/apache2/ports.conf +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Listen 80 Listen 8080 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ /etc/apache2/ports.conf does not require NameVirtualHost. Do not add it if it is missing or already there. Just prepend # accordingly. FILE PARTIAL (CONFIRM/ADD/CHANGE): /etc/apache2/ports.conf +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ #NameVirtualHost *:80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Disable Default Site ================================================================= These short instructions assume that the default site is not needed. Talk with your system administrator, network administrator, or IT Department to CONFIRM THIS BEFORE RUNNING the following command: sudo a2dissite 000-default Enable Modules and Site ================================================================= Now enable the Apache modules this config needs, enable Koha's virtual host configuration, and restart Apache. sudo a2enmod rewrite sudo a2enmod deflate sudo a2ensite koha sudo service apache2 restart SETUP ZEBRA ================================================================= The Zebra process send responses to search requests sent by Koha or Z39.50/SRU/SRW clients. The user you run Zebra as will be the only user with write permission on the Zebra index. For a standard installation, this should be the system user 'koha'. For a dev installation, this should be your system user. Start Zebra Server on Boot ================================================================= IF YOU ARE DOING A STANDARD INSTALLATION, use this command: sudo ln -s /usr/share/koha/bin/koha-zebra-ctl.sh \ /etc/init.d/koha-zebra-daemon IF YOU ARE DOING A DEV INSTALLATION, use this command: sudo ln -s ~/koha-dev/bin/koha-zebra-ctl.sh \ /etc/init.d/koha-zebra-daemon FOR EITHER INSTALLATION: sudo update-rc.d koha-zebra-daemon defaults sudo service koha-zebra-daemon start Configuring Zebra Indexing ================================================================= IF YOU ARE DOING A STANDARD INSTALLATION, use this command: sudo nano /etc/cron.d/koha FILE FULL: /etc/cron.d/koha +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ # The cronjobs -- $KOHA_PATH is defined in /etc/environment, and # gets set when this process runs as a user (koha). */5 * * * * koha $KOHA_PATH/bin/migration_tools/rebuild_zebra.pl -b -a -z &> /dev/null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ IF YOU ARE DOING A DEV INSTALLATION, use this command: crontab -e FILE PARTIAL (ADD): +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ # The cronjobs -- $KOHA_PATH is defined in /etc/environment, and # gets set when this process runs. */5 * * * * $KOHA_PATH/misc/migration_tools/rebuild_zebra.pl -b -a -z &> /dev/null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ SETUP ADDITIONAL LANGUAGES ================================================================= To use multi-lingual sample data, please install languages which may be useful for use in the Koha system. Information on this can be found: http://wiki.koha-community.org/wiki/Installation_of_additional_languages_for_OPAC_and_INTRANET_staff_client WEB INSTALLATION ================================================================= Now you can visit your staff client website to continue with the Koha web installer. The user name to log in with will be koha. The password will be what you set in the 'Create User and Grant Permissions' section above. Lynx navigational keys include: tab to go between fields, enter (when not on text fields) to toggle or click, space to change pages (when not on text fields), Q to quit (when not on text fields). Arrows also work. sudo apt-get install lynx lynx http://127.0.1.1:8080/ SET UP YOUR LIBRARY IN KOHA ================================================================= After the web install, you should be redirected to: http://127.0.1.1:8080 Follow these steps: - Login with koha user name and password. - Click on the More dropdown menu. - Select and click Administration. - Click Libraries and groups under the Basic Parameters heading. - Click New Library and enter your information into the form. - Click Submit. Your library is now set up in Koha. Take the time to read the documentation to do other necessary setup tasks such as creating a patron, and importing or entering MARC data. The documentation for Koha can be found at: http://koha-community.org/documentation/ USEFUL REFERENCE LINKS ================================================================= Documentation: http://koha-community.org/documentation/ Additional Languages: http://wiki.koha-community.org/wiki/Installation_of_additional_languages_for_OPAC_and_INTRANET_staff_client Stage MARC Records for Import: http://manual.koha-community.org/3.14/en/catalogtools.html#stagemarc NOTE: The URL has been similar since Koha version 3.8 Frequently Asked Questions: http://koha-community.org/documentation/faq Bug Reports: http://bugs.koha-community.org/ Public Z39.50/SRU server: http://wiki.koha-community.org/wiki/Troubleshooting_Koha_as_a_Z39.50_server Alternate Indexing Method: http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra UPGRADING ================================================================= If you are running in another language other than English, please switch to English before doing the upgrade, the templating system has changed and the templates will need to be regenerated. Once you have upgraded, please regenerate your templates in your chosen languages. First, ensure the most recent dependencies are installed: sudo apt-get update sudo apt-get install koha-deps koha-perldeps IF YOU ARE DOING A STANDARD UPGRADE: In order to upgrade, find the path to the koha install-log file: sudo find /usr/share/koha/ -name 'koha-install-log' Change directory into the latest koha source directory, and then: perl Makefile.PL --prev-install-log /path/to/koha-install-log NOTE: Make sure to change the /path/to/koha-install-log to the one that was found. make make test And if that passes: sudo make upgrade IF YOU ARE DOING A DEV UPGRADE: In order to upgrade, find the path to the koha install-log file: find ~/koha-dev/ -name 'koha-install-log' cd ~/kohaclone perl Makefile.PL --prev-install-log /path/to/koha-install-log NOTE: Make sure to change the /path/to/koha-install-log to the one that was found. make make test And if that passes: make upgrade FOR EITHER UPGRADE TYPE: If you are upgrading from a version of Koha earlier than 3.4.x, Koha 3.4.x or later no longer stores items in biblio records: ./misc/maintenance/remove_items_from_biblioitems.pl --run Intentionally not indented, in the hopes that most upgrades are post 3.4.x. Regardless of version you are upgrading from, a full reindex is always the best option: IF YOU ARE DOING A STANDARD UPGRADE sudo su -l koha --command="/usr/bin/perl /usr/share/koha/bin/migration_tools/rebuild_zebra.pl -b -a -r -v" IF YOU ARE DOING A DEV UPGRADE ./misc/migration_tools/rebuild_zebra.pl -b -a -r -v UNINSTALL INSTRUCTIONS ================================================================= Stop Services ================================================================= sudo a2dissite koha sudo rm /etc/apache2/sites-available/koha sudo service apache2 restart sudo update-rc.d koha-zebra-daemon remove sudo rm /etc/init.d/koha-zebra-daemon Remove Database ================================================================= mysql -u koha -p drop database kohadata; quit Remove Indexes ================================================================= IF DOING A STANDARD REMOVAL: zebraidx -c /etc/koha/zebradb/zebra-biblios.cfg \ -g iso2709 -d biblios init zebraidx -c /etc/koha/zebradb/zebra-authorities.cfg \ -g iso2709 -d authorities init sudo rm -rf /etc/koha sudo rm -rf /usr/share/koha sudo rm /etc/cron.d/koha You may wish to follow up with: sudo find / -t d -name "koha" to help find any remnants. IF DOING A DEV REMOVAL: The following will work, but is very dangerous! Please copy or type this correctly. zebraidx -c ~/koha-dev/etc/zebradb/zebra-biblios.cfg \ -g iso2709 -d biblios init zebraidx -c ~/koha-dev/etc/zebradb/zebra-authorities.cfg \ -g iso2709 -d authorities init rm -rf ~/koha-dev rm -rf ~/kohaclone NOTE: Don't forget to remove the crontab entries! LICENSE ================================================================= This file is part of Koha. Major re-write by Mark Tompsett Copyright (C) 2013 Based on remnants by: Copyright (C) 2007, 2008 LibLime (http://liblime.com) Original author: Joshua Ferraro Some parts Copyright (C) 2010 Chris Nighswonger (modified for ubuntu) (cnighswonger AT foundations DOT edu) Some parts Copyright (C) 2012 Tomas Cohen Arazi (tomascohen AT gmail DOT com) Some parts Copyright (C) 2012 Mark Tompsett (mtompset AT hotmail DOT com) Koha is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. Koha is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Koha; if not, see .