From 4b9af3c307c99b1c6ca680903e1902bcc2f75cac Mon Sep 17 00:00:00 2001 From: Mark Tompsett Date: Tue, 27 Aug 2013 17:29:20 -0400 Subject: [PATCH] Bug 7764: rework the INSTALL.ubuntu instructions This is a major rework. Key improvements include: - Removed confusing multiple versions for Ubuntu leaving only one set of instructions. - The packages koha-deps and koha-perldeps are used. - License has been updated to reflect GPL3. - More wiki reference links have been included. - It is aimed to be based on source, not just tarball or just git. - Sample output has been cut as much as possible. - Almost cut-and-paste easy, making it friendlier than INSTALL.debian. Signed-off-by: Tomas Cohen Arazi Signed-off-by: Katrin Fischer Fixed a tiny typo: seperate Makes all sense to me - only wondering a bit about the recommendation of using lynx for the web installer. Quite an improvement, so passing QA. Signed-off-by: Galen Charlton (cherry picked from commit c63770d81581080a9c714172fd36ceb86c08062d) Signed-off-by: Tomas Cohen Arazi --- INSTALL.ubuntu | 828 ++++++++++++++++++++++++++++--------------- INSTALL.ubuntu.12.04 | 571 ----------------------------- INSTALL.ubuntu.lucid | 380 -------------------- 3 files changed, 538 insertions(+), 1241 deletions(-) delete mode 100644 INSTALL.ubuntu.12.04 delete mode 100644 INSTALL.ubuntu.lucid diff --git a/INSTALL.ubuntu b/INSTALL.ubuntu index 050d15d7e9..93190d029d 100644 --- a/INSTALL.ubuntu +++ b/INSTALL.ubuntu @@ -1,448 +1,696 @@ -============================= -Installation Guide for Installing Koha on Ubuntu Jaunty (9.04) with MySQL 5 -============================= +================================================================= +Instructions for Installing Koha from Source +================================================================= -Copyright (C) 2007, 2008 LibLime (http://liblime.com) -Some parts copyright 2010 Chris Nighswonger +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. -Original author: Joshua Ferraro -Modified for Ubuntu by: Chris Nighswonger (cnighswonger AT foundations DOT edu) +Bug reports can be posted at http://bugs.koha-community.org -Feedback/bug reports: Koha Developer's List: +Feedback can be posted on the Koha Developer's List: http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel -This document last modified: 20 March 2010 -Installation Instructions -============================= +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. + +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 relately 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 in credentials and not one called koha. This is to prevent +the system user koha from having more permissions than it should. + -All commands can be performed as a system user with sudo privileges, -as indicated or by running the command directly as root. +ADD A KOHA COMMUNITY REPOSITORY +================================================================= -1. Prepare System and Install Dependencies +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. -1.1 Install Ubuntu Jaunty via CD +To avoid getting prompted for a password in the middle of a +chain of commands type the following: + sudo ls -See http://www.ubuntu.com/getubuntu/download +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 -1.2 Set up your locale +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 -Your locale should be set to UTF-8, as should Apache2 and MySQL 5. -This step is VERY IMPORTANT for a UNICODE compliant system. Please -read over the following document carefully: +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. -http://wiki.koha-community.org/wiki/Encoding_and_Character_Sets_in_Koha +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 - -You can verify your system locale by typing the following command: - $ locale +UPDATE UBUNTU +================================================================= -IMPORTANT: You _MUST_ follow all the steps outlined there for - Apache2, MySQL 5, etc. BEFORE you install Koha. +This process, particularly the upgrade step, may take a while. -1.3 Install the Yaz and Zebra packages + sudo apt-get update -Run the following command to update your system: + sudo apt-get upgrade - $ sudo apt-get update - $ sudo apt-get install yaz idzebra-2.0 idzebra-2.0-doc + sudo apt-get clean -1.4 Get Koha -1.4.1 Option A: Download Koha via Git (optional) +DOWNLOAD THE LATEST KOHA RELEASE +================================================================= - $ sudo apt-get install git-core git-email - $ git clone git://git.koha-community.org/koha.git kohaclone - $ cd kohaclone - $ git checkout -b myinstall origin +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. -Note: for more information about Git, please see the Koha Git Usage Guide: +IF YOU ARE DOING A STANDARD INSTALLATION: +Downloading Source Via Tarball +================================================================= - http://wiki.koha-community.org/wiki/Version_Control_Using_Git + wget http://download.koha-community.org/koha-latest.tar.gz + tar xvf koha-latest.tar.gz + ls -1.4.2 Option B: Download Koha from http://download.koha-community.org +NOTE: You need to cd into the koha directory, but since the +version changes, you'll know by the ls command what it is. - $ wget http://download.koha-community.org/koha-3.00.02.tar.gz - ( Note: use the latest stable version) +IF YOU ARE DOING A DEV INSTALLATION: +Downloading Source Via Git +================================================================= -1.5 Install additional Ubuntu dependencies +Please see the following wiki page, following the instructions up +to and including "git checkout -b mywork origin". +http://wiki.koha-community.org/wiki/Version_Control_Using_Git -IMPORTANT: You should only use CPAN for Perl dependencies which are NOT - available from the package maintainer. You have been warned! -Using the ubuntu.packages file included in the Koha source tree, -run the following: +INSTALL DEPENDENCIES +================================================================= - $ sudo dpkg --set-selections < install_misc/ubuntu.packages +Dependencies from Repository +================================================================= -Now start dselect (you may need to 'sudo apt-get install dselect'): +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 - $ sudo dselect +Check For Missing Dependencies +================================================================= -Choose [I]nstall and accept packages to be installed (hit return) +Check everything was installed, by running the test script to +identifty missing libraries: + ./koha_perl_deps.pl -m -u -(may take a while) +Install any required libraries that are missing. It is a good +idea to install optional ones that are easily found as well. -Choose [C]onfigure, [R]emove and [Q]uit until dselect has completed. -1.6 Install Perl dependencies that aren't packaged into Ubuntu Jaunty -sources +CREATE MYSQL DATABASE AND GRANT PRIVILEGES +================================================================= -Run the following command: +Create MySQL Database +================================================================= - $ sudo cpan GD GD::Barcode::UPCE Algorithm::CheckDigits::M43_001 CHI CHI::Driver::Memcached +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 -Note: you may need to run CPAN initialization if you've not run cpan -before: + mysql -u root -p - /etc/perl/CPAN/Config.pm initialized. + CREATE DATABASE kohadata; - CPAN is the world-wide archive of perl resources. It consists of about - 100 sites that all replicate the same contents all around the globe. - Many countries have at least one CPAN site already. The resources - found on CPAN are easily accessible with the CPAN.pm module. If you - want to use CPAN.pm, you have to configure it properly. +The koha database has now been created with the name kohadata. - If you do not want to enter a dialog now, you can answer 'no' to this - question and I'll try to autoconfigure. (Note: you can revisit this - dialog anytime later by typing 'o conf init' at the cpan prompt.) +Create User and Grant Permissions +================================================================= - Are you ready for manual configuration? [yes] +Continue entering MySQL commands. SUBSTITUTE A PASSWORD OF YOUR +CHOICE FOR THE {PASSWORD}'S IN THE FOLLOWING COMMANDS: -When the configuration is completed CPAN will install the Perl modules. + CREATE user 'koha'@'localhost' IDENTIFIED by '{PASSWORD}'; + GRANT ALL ON kohadata.* TO 'koha'@'localhost' IDENTIFIED BY '{PASSWORD}'; + FLUSH PRIVILEGES; + QUIT -2. Configuration of dependencies +The koha administrative user has now been created with the name +koha and the password of your choosing. -2.1 Update root MySQL password (if dselect didn't do it for you already) - $ sudo mysqladmin password +CONFIGURE KOHA +================================================================= -2.2 Create the Koha database +User/Group Environment Variables +================================================================= - Create the database and user with associated privileges: +IF YOU ARE DOING A STANDARD INSTALLATION, then create a +separate koha system user: + sudo adduser koha - $ mysqladmin -uroot -p create - $ mysql -uroot -p +There is no need to set the following environment variables, +because koha is the default account to use. - Welcome to the MySQL monitor. Commands end with ; or \g. - Your MySQL connection id is 22 - Server version: 5.0.32-Debian_7etch3-log Debian etch distribution +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 - Type 'help;' or '\h' for help. Type '\c' to clear the buffer. +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. - mysql> grant all on .* to ''@'localhost' identified by ''; - Query OK, 0 rows affected (0.00 sec) - mysql> flush privileges; - Query OK, 0 rows affected (0.00 sec) +Configure Your Koha Install +================================================================= - mysql> quit + perl Makefile.PL -2.3 Test your SAX Parser and correct where necessary +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. - You must be sure you're using the XML::LibXML SAX parser, not Expat or PurePerl, both of which have outstanding bugs with pre-composed characters. You can test your SAX parser by running: +Answering the resulting questions requires thinking. Here are +some hints. - $ cd koha - $ misc/sax_parser_print.pl +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. - You should see something like:: +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. - XML::LibXML::SAX::Parser=HASH(0x81fe220) +Use the same username and password for the Zebra questions. - If you're using PurePerl or Expat, you'll need to edit your - ini file, typically located at: +Don't worry about warnings generated by optional components. - /etc/perl/XML/SAX/ParserDetails.ini - You will need to move the entire section for '[XML::LibXML::SAX::Parser]' to the bottom of the ini file. +Build And Test Koha +================================================================= -2.4 Install DBD::mysql Perl module +Having configured Koha, build it using the following command: + make -In order to handle UTF-8 correctly, Koha requires at least version 4.004 -of the DBD::mysql Perl module. However, Debian Etch has a stable package -only for version 3.0008, so it is necessary to install the module from CPAN. -DBD::mysql's test suite needs to use a MySQL 'test' DB which doesn't exist -anymore. So there are two options to install DBD::mysql: +Once this has successfully run, test Koha using the following +command: + make test - (1) install without test suite, - (2) install with test suite requiring a test MySQL DB creation. +Don't worry about the large number of scary warning scrolling +by. All that matters is "PASS" or "FAIL". -2.4.1 Install without test suite +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. -Force install DBD::mysql: - $ sudo cpan - cpan> force install DBD::mysql +Install Koha +================================================================= -2.4.2 Create test database in order to install DBD::mysql +Once the make test has successfully run, install Koha. -Because of DBD::mysql's test suite, it is necessary to temporarily create a -test database and user: +IF YOU ARE DOING A STANDARD INSTALLATION, using the +following command (follow any on screen prompts): + sudo make install - $ mysql -uroot -p +Once this has successfully run, Koha is almost installed. There +are only a few more steps left. - Create the database and user with associated privileges: +IF YOU ARE DOING A DEV INSTALLATION, using the +following command (follow any on screen prompts): + make install - Welcome to the MySQL monitor. Commands end with ; or \g. - Your MySQL connection id is 22 - Server version: 5.0.32-Debian_7etch3-log Debian etch distribution +No sudo is required as you have access to the directories +listed above. - Type 'help;' or '\h' for help. Type '\c' to clear the buffer. +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. - mysql> create database test; - Query OK, 1 row affected (0.00 sec) - mysql> grant all on test.* to 'test'@'localhost' identified by 'test'; - Query OK, 0 rows affected (0.00 sec) - (test database, user, and password can be different if need be) +PRE-WEB INSTALL SETUP +================================================================= - mysql> flush privileges; - Query OK, 0 rows affected (0.00 sec) +Ubuntu MySQL Security Tweak +================================================================= - mysql> quit +There is a security risk in Ubuntu's MySQL default set up. Type +the following commands: + mysql -u root -p -Next install DBD::mysql: + USE mysql; + DELETE FROM user WHERE user=''; + FLUSH PRIVILEGES; + QUIT - $ sudo cpan +The anonymous connections are now removed. - cpan> o conf makepl_arg - (get current value of this CPAN parameter) - cpan> o conf makepl_arg "--testdb=test --testuser=test --testpass=test" +Configure System Wide Environment Variables +================================================================= - cpan> install DBD::mysql +Running scripts and cron jobs requires environment variables set. +Use the following commands: + sudo nano /etc/environment - cpan> o conf makepl_arg '' +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! - OR +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 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - cpan> o conf makepl_arg '' + logout - (restore this setting so as to not interfere with future CPAN installs). +You need to logout and back in in order to get the environment +variables values to be recognized. -Finally, remove the test database: +CONFIGURE AND START APACHE +================================================================= - $ mysql -uroot -p +Place Koha Site File +================================================================= - mysql> drop database test; - Query OK, 1 row affected (0.00 sec) +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 - mysql> exit - Bye +IF YOU ARE DOING A STANDARD INSTALLATION, use the following +command: + sudo ln -s /etc/koha/koha-httpd.conf \ + /etc/apache2/sites-available/koha -3. Run the Koha installer +Tweak Koha Site File +================================================================= - $ perl Makefile.PL - ( answer questions ) - $ make - $ make test - $ sudo make install +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 -4. Configure and start Apache - $ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha - (note that the path to koha-httpd.conf may be different depending on your - installation choices) +/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 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Add the following lines to /etc/apache2/ports.conf: +/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 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - Listen 80 - Listen 8080 +Setup Default Ports +================================================================= -If not running named virtual hosts (The default koha installation does not use named virtual hosts.), comment out the following line: + sudo nano /etc/apache2/ports.conf - NameVirtualHost *:80 +/etc/apache2/ports.conf must have two lines exactly like +the following. Do not add them if they are already there. -Run the following commands: +FILE PARTIAL (CONFIRM/ADD/CHANGE): /etc/apache2/ports.conf ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +Listen 80 +Listen 8080 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - $ sudo a2enmod rewrite deflate - $ sudo a2ensite koha - $ sudo apache2ctl restart +/etc/apache2/ports.conf does not require NameVirtualHost. +Do not add it if it is missing or already there. Just +prepend # accordingly. -Note: you may still see the usual Apache default site if your VirtualHost -configuration isn't correct. The command "sudo a2dissite default" may be a -quick fix, but may have side-effects. See the Apache HTTPD manual section on -virtual hosts for full instructions. +FILE PARTIAL (CONFIRM/ADD/CHANGE): /etc/apache2/ports.conf ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +#NameVirtualHost *:80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -5. Configure and start Zebra +Disable Default Site +================================================================= -Note: it's recommended that you daemonize the Zebra process and add it to your -startup profile. For a non-production test/development installation, running -Zebra from the command line can be useful. Pick from the two available options -below, or roll your own :-) +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 -Note: it's also recommended that you create a Koha system user, which you will -have specified during the install process. Alternatively, Zebra can be -configured to run as the root user. +Enable Modules and Site +================================================================= -To add a user do: +Now enable the apache modules this config needs, enable koha's +configuration, and restart apache. + sudo a2enmod rewrite + sudo a2enmod deflate + sudo a2ensite koha + sudo service apache2 restart - $ sudo adduser koha -Option 1: run the Zebra processes from the command line: +SETUP ZEBRA +================================================================= -5.1.1 Zebra Search Server +The zebra process send responses to search requests sent by Koha +or Z39.50/SRU/SRW clients. -This 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. - $ sudo -u ${KOHA_USER} zebrasrv -f /etc/koha/koha-conf.xml - (note that the path to koha-conf.xml may be different depending on your - installation choices) +Start Zebra Server on Boot +================================================================= -Note: the user you run Zebra as will be the only user with write permission - on the Zebra index; in development mode, you may wish to use your - system user. +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 -5.1.2 Zebra Indexer +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 -Added/updated/deleted records in Koha MySQL database must be indexed -into Zebra. A specific script must be launched each time a bibliographic -or an authority record is edited. +FOR EITHER INSTALLATION: + sudo update-rc.d koha-zebra-daemon defaults + sudo service koha-zebra-daemon start - $ sudo -u ${KOHA_USER} misc/migration_tools/rebuild_zebra -z -b -a - NOTE: This script should be run as the kohauser (the default is 'koha'). +Configuring Zebra Indexing +================================================================= -Option 2: run the Zebra process as a daemon, and add to startup process: +IF YOU ARE DOING A STANDARD INSTALLATION, use this command: + sudo nano /etc/cron.d/koha -Note that references to $SCRIPT_DIR refer to the directory where -Koha's command-line scripts are installed, e.g., /usr/share/koha/bin. +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 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -5.2.1 Zebra Search Server +IF YOU ARE DOING A DEV INSTALLATION, use this command: + crontab -e - $ sudo ln -s ${SCRIPT_DIR}/koha-zebra-ctl.sh /etc/init.d/koha-zebra-daemon - (Note: ${SCRIPT_DIR} is /usr/share/koha/bin/ by default in a standard install) - $ sudo update-rc.d koha-zebra-daemon defaults - ( Note: see man chkconfig(8) on other distros ) +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 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - $ sudo ${SCRIPT_DIR}/koha-zebra-ctl.sh start -5.2.2 Zebra Indexer +SETUP ADDITIONAL LANGUAGES +================================================================= -Add an entry in Koha user crontab to scheduled added/updated/deleted records -indexing by Zebra with this command: +To use multi-lingual sample data, please install languages +which may be useful for use in the Koha system. - /misc/migration_tools/rebuild_zebra -z -b -a +Information on this can be found: +http://wiki.koha-community.org/wiki/Installation_of_additional_languages_for_OPAC_and_INTRANET_staff_client -See check misc/cronjobs/crontab.example for usage examples. -NOTE: This job should be setup under the kohauser (the default is 'koha'). -You can also configure zebra-indexing as an background daemon, see http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra +WEB INSTALLATION +================================================================= -6. Run the Web Installer, populate the database, initial configuration of settings +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. - Point your browser to http://:8080/ +The password will be what you set in the 'Create User and +Grant Permissions' section above. - It should redirect you to the Web Installer where you can continue the setup. - You can install the sample data for libraries, patrons, etc. via the Web Installer +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. -7. What next? + sudo apt-get install lynx - Once the installer has completed, you can import and index MARC records from the - command line thusly (Note: you can also use the 'Stage MARC records for import' from - the Tools area of Koha's Staff Client to import a batch of MARC records): + lynx http://127.0.1.1:8080/ - $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml - (note: use the correct path to your koha-conf.xml) -7.1 Import: - Bibliographic data in MARC21 format - $ misc/migration_tools/bulkmarcimport.pl -file /path/to/marc.iso2709 - Authority data in MARC21 format - $ misc/migration_tools/bulkauthimport.pl -file /path/to/auth.iso2709 +SETUP YOUR LIBRARY IN KOHA +================================================================= -7.2 Fast Index: - $ misc/migration_tools/rebuild_zebra.pl -b -w +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 setup in Koha. - Once the indexing has completed, you will be able to search for records in your system. - NOTE: This script should be run as the kohauser (the default is '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/ -7.3 Schedule regular index updates - You need to run rebuild_zebra.pl -b -a -z as a regular cron job in orde to pick up new bibs - and items as you add them. Check misc/cronjobs/crontab.example for usage examples. See 7.0 above. - NOTE: This job should be setup under the kohauser (the default is 'koha'). +USEFUL REFERENCE LINKS +================================================================= - You can also indexing in background, see 5.2.2 above +Documentation: +http://koha-community.org/documentation/ -7.4 To enable public Z39.50/SRU servers, you'll need to edit your koha-conf.xml and - change the options to listen on a TCP port; then restart the zebra daemon. +Additional Languages: +http://wiki.koha-community.org/wiki/Installation_of_additional_languages_for_OPAC_and_INTRANET_staff_client -UPGRADE -======= -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. +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 -If you are upgrading from a previous installation of Koha 3.x, you can -use the following: +Frequently Asked Questions: +http://koha-community.org/documentation/faq - ./koha_perl_deps.pl -u -m # to identify new Perl dependencies +Bug Reports: +http://bugs.koha-community.org/ -Install any missing modules -IMPORTANT: Koha 3.6.x uses Template::Toolkit, this must be installed -before the webinstaller can run +Public Z39.50/SRU server: +http://wiki.koha-community.org/wiki/Troubleshooting_Koha_as_a_Z39.50_server - sudo apt-get install libtemplate-perl +Alternate Indexing Method: +http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra - perl Makefile.PL --prev-install-log /path/to/koha-install-log - make - make test - sudo make upgrade -Koha 3.4.x or later no longer stores items in biblio records so -if you are upgrading from an older version as part of the -upgrade you will need to do the following two steps, they can take a -long time (several hours) to complete for large databases +UPGRADING +================================================================= - misc/maintenance/remove_items_from_biblioitems.pl --run - misc/migration_tools/rebuild_zebra.pl -b -r +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. -Uninstall Instructions -============================= -1) Stop Services: - $ sudo a2dissite koha - $ sudo rm /etc/apache2/sites-available/koha - $ sudo apache2ctl restart +Once you have upgraded, please regenerate your templates in +your chosen languages. - $ sudo update-rc.d koha-zebra-daemon remove - $ sudo rm /etc/init.d/koha-zebra-daemon +First, ensure the most recent dependencies are installed: + sudo apt-get update + sudo apt-get install koha-deps koha-perldeps -2) Remove Database and Indexes +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' - # MySQL - $ mysql -u -p - > drop database koha; +Change directory into the latest koha source directory, and then: + perl Makefile.PL --prev-install-log /path/to/koha-install-log - # Zebra Indexes - $ zebraidx -c /etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init - $ zebraidx -c /etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init +NOTE: Make sure to change the /path/to/koha-install-log to the +one that was found. -3) Remove Koha Install Directories and Configuration Files - Don't forget about any crontab entries + make + make test -Tested on the following operating environments -============================================== -- Ubuntu Jaunty Jackalope 9.04 +And if that passes: + sudo make upgrade -Installer Bug reports -===================== -Please log any installer bug reports at http://bugs.koha-community.org +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' -Other Notes -===================== -This file is part of Koha + cd ~/kohaclone + perl Makefile.PL --prev-install-log /path/to/koha-install-log -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 2 of the License, or (at your option) any later -version. +NOTE: Make sure to change the /path/to/koha-install-log to the +one that was found. -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, write to the Free Software Foundation, Inc., -51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + 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 . diff --git a/INSTALL.ubuntu.12.04 b/INSTALL.ubuntu.12.04 deleted file mode 100644 index a1073865bb..0000000000 --- a/INSTALL.ubuntu.12.04 +++ /dev/null @@ -1,571 +0,0 @@ -================================================================= -Installation Guide for Installing Koha -on Ubuntu Precise Pangolin (12.04 LTS) with MySQL 5.5 -================================================================= - -Copyright (C) 2007, 2008 LibLime (http://liblime.com) -Some parts copyright 2010 Chris Nighswonger -Some parts copyright 2012 Tomas Cohen Arazi -Some parts copyright 2012 Mark Tompsett - -Original author: Joshua Ferraro -Modified for Ubuntu by: Chris Nighswonger - (cnighswonger AT foundations DOT edu) - -More updates by: Tomas Cohen Arazi (tomascohen AT gmail DOT com) - Mark Tompsett (mtompset AT hotmail DOT com) - -Feedback/bug reports: Koha Developer's List: -http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel - -This document last modified: 24 July 2012 - -Installation Instructions -================================================================= - -Running commands can mostly be performed as a system user with -sudo privileges, however some need to be run directly as root. - -1. Prepare System and Install Dependencies - -1.1 Install Ubuntu 12.04 LTS via CD/DVD/USB - - Download and install Ubuntu from the official site. - - Server edition (command-line only) - http://www.ubuntu.com/download/server - - Desktop edition - http://www.ubuntu.com/download/desktop - To keep your Koha installation minimal and to free resources - for running, the Server edition is recommended, though the - Desktop edition will work as well. - - As Apache and MySQL will be installed in the instructions - later, there is no need to select any packages during the - installation of Ubuntu. - -1.2 Add koha repository to your apt sources - - NOTE: This is not required for koha 3.6.7 under Ubuntu 12.04 - if Zebra indexing (see step 5.2) is done via cron jobs. - NOTE: 3.8.x is the recommended current stable release to use. - - There are currently three active repositories: oldstable, - squeeze, and squeeze-dev. As of 2012-07-24, they represent - 3.6.x, 3.8.x, and master respectively. This will change when - 3.10.x is released. They will represent 3.8.x, 3.10.x, and - master respectively. - - It is recommended to use squeeze at this time, as 3.8.x is the - current stable release. - - Run these commands: - $ echo "deb http://debian.koha-community.org/koha squeeze main" | sudo tee /etc/apt/sources.list.d/koha-community.list - $ wget -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add - - $ sudo apt-get update ; sudo apt-get upgrade - -1.3 Install Apache2 and MySQL 5.5 - - Install the Apache2 server: - $ sudo apt-get install apache2 - - If your MySQL server will be on your Koha server, or this - instruction is confusing: - $ sudo apt-get install mysql-server - - NOTE: You will be prompted to set your root password for MySQL. - -1.4 Set up your locale - - Your locale should be set to UTF-8, as should Apache2 and - MySQL 5.5. This step is VERY IMPORTANT for a UNICODE compliant - system. You _MUST_ be sure to set this BEFORE you install Koha. - -1.4.1 Ubuntu Locale - - Verify you have a UTF-8 locale in use: - $ locale - You will recognize if it is UTF-8 or not. Ubuntu 12.04 should - not generally require any further steps. - - If it is not set to something UTF-8, use: - $ locale -a - - You can select one (note that utf8 becomes UTF-8) and use: - $ sudo update-locale LANG=en_US.UTF-8 - - You have to log out and back in to see locale change reflected - in the locale command. - - Verify your system local by running the following command: - $ locale - -1.4.2 Apache2 and MySQL Locales - Please read over the following document carefully for more - information: - http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Configuring_the_Character_Set - -1.5 Get Koha - - There are two ways to install Koha. The easy way is using Debian/Ubuntu - packages (check http://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages - for further instructions). - - The other way is installing from sources. You can get Koha's source - either using git (see 1.5.1) or downloading the stable release tarball. - - 1.5.1 Download from Git - - Install Git: - $ sudo apt-get install git - - Download Koha (the 3.10.x branch): - $ git clone git://git.koha-community.org/koha.git kohaclone - $ cd kohaclone - $ git checkout -b myinstall origin/3.10.x - - NOTE: for more information about Git, please see the Koha Git - Usage Guide: - http://wiki.koha-community.org/wiki/Version_Control_Using_Git - - 1.5.2 Download from Tarball - - You can get the sources from - http://download.koha-community.org. Issuing the following - command you can get the latest stable release (recommended): - - Download and Unpack Koha: - $ wget http://download.koha-community.org/koha-latest.tar.gz - $ tar xvf koha-latest.tar.gz - - Determine the version and change directory: - $ ls - koha-3.10.00 koha-latest.tar.gz - $ cd koha-3.10.00 - - -1.6 Install additional Ubuntu dependencies - - Several Koha dependencies have been conveniently packaged and - will be installed issuing the following command: - - $ sudo apt-get install `cat install_misc/ubuntu.12.04.packages | \ - cut -f1 | grep -v '#' | grep -v -e '^$'` - - Confirm that you want to install the required packages when prompted, - -1.7 Install Perl dependencies that aren't packaged - -**************************************************************** - IMPORTANT: You should only use CPAN for Perl dependencies - which are NOT available from the package - maintainer. You have been warned! -**************************************************************** - - Run the test script to identify missing libraries - $ ./koha_perl_deps.pl -m -u - - If there are any dependencies which are missing or need - upgrading, first attempt aptitude searches: - $ aptitude search libbusiness-isdn-perl - - Notice how the name transformed to 'lib' plus the lowercase - library name using '-'s instead of '::'s plus '-perl'. This - will generally help find what is missing. And then a simple - apt-get install can be done: - $ sudo apt-get install libbusiness-isdn-perl - - Do this for all the dependencies listed. Then re-run the - command: - $ ./koha_perl_deps.pl -m -u - - In general, the repositories on debian.koha-community.org - should have any missing pieces. The list should be empty. - - If any are still listed, they can be installed using the 'cpan' - command. If and only if you are unable to find any of the - dependencies should you use the cpan command. For example: - $ sudo cpan GD GD::Barcode::UPCE Algorithm::CheckDigits - - NOTE: you may need to run CPAN initialization if you've not run - cpan before: --------- - /etc/perl/CPAN/Config.pm initialized. - - CPAN is the world-wide archive of perl resources. It consists of about - 100 sites that all replicate the same contents all around the globe. - Many countries have at least one CPAN site already. The resources - found on CPAN are easily accessible with the CPAN.pm module. If you - want to use CPAN.pm, you have to configure it properly. - - If you do not want to enter a dialog now, you can answer 'no' to this - question and I'll try to autoconfigure. (Note: you can revisit this - dialog anytime later by typing 'o conf init' at the cpan prompt.) - - Are you ready for manual configuration? [yes] --------- - When the configuration is completed CPAN will install the Perl - modules passed on the command-line. - - For further explanation and reading see: - http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Ubuntu_Packages_for_Perl_Dependencies - - -2. Configuration of dependencies - -2.1 Update root MySQL password - - If during the installation of MySQL you were not prompted to - set the MySQL password: - $ sudo mysqladmin password - -2.2 Create the Koha database - - Create the database and user with associated privileges. To do - this, decide on the koha database name, the koha user name, and - the koha user password. Substitute these into the following - commands: - $ mysql -u root -p - Enter mysql root password: - Welcome to the MySQL monitor. Commands end with ; or \g. - Your MySQL connection id is 42 - Server version: 5.5.24-0ubuntu0.12.04.1 (Ubuntu) - - Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved. - - Oracle is a registered trademark of Oracle Corporation and/or its - affiliates. Other names may be trademarks of their respective - owners. - - Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. - - mysql> CREATE DATABASE {kohadatabasename}; - mysql> SHOW DATABASES; - mysql> CREATE user '{kohauserbasename}'@'localhost' IDENTIFIED by '{kohauserpassword}'; - mysql> GRANT ALL ON {kohadatabasename}.* TO '{kohausername}'@'localhost' IDENTIFIED BY '{kohauserpassword}'; - mysql> USE mysql; - mysql> SELECT host,user FROM user; - mysql> DELETE FROM user WHERE user=''; - mysql> SELECT host,user FROM user; - mysql> FLUSH PRIVILEGES; - mysql> QUIT - - For further explanation of these commands see: - http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Create_MySQL_Database_and_Grant_Privileges - - -2.3 Test your SAX Parser and correct where necessary - - You must be sure you're using the XML::LibXML SAX parser, not - Expat or PurePerl, both of which have outstanding bugs with - pre-composed characters. Test your SAX parser by running: - $ ./misc/sax_parser_print.pl - - If your setup is wrong, the script will output something like: - Koha wants something like: - XML::LibXML::SAX::Parser=HASH(0x81fe220) - You have: - XML::SAX::Expat=HASH(0x1a94e88) - Looks bad, check INSTALL.* documentation. - - It means you are using Expat (it could also say PurePerl). - You'll need to edit your ini file, located at: - /etc/perl/XML/SAX/ParserDetails.ini - - Move the entire section for '[XML::LibXML::SAX::Parser]' to the - bottom of the ini file. Then run the script again. The output - should look like this: - $ misc/sax_parser_print.pl - Koha wants something like: - XML::LibXML::SAX::Parser=HASH(0x81fe220) - You have: - XML::LibXML::SAX::Parser=HASH(0x16dfee8) - Looks good. - - For further details see: - http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Test_to_make_sure_the_SAX_Parser_is_setup_correctly - - -3. Run the Koha installer - - Add a user for installing koha and running zebra: - $ sudo adduser koha - - Build and install Koha: - $ perl Makefile.PL - ( answer questions ) - $ make - $ make test - $ sudo make install - - -4. Configure and start Apache - - This will help make koha available to be a website: - $ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha - - NOTE: the path to koha-httpd.conf may be different depending on - your installation choices. - - Make sure you have this lines in /etc/apache2/ports.conf: - Listen 80 - Listen 8080 - Add the missing one. - - The default installation of Koha does not use named virtual - hosts. If you will not be running named virtual hosts, comment - out the following line: - NameVirtualHost *:80 - - Run the following commands: - $ sudo a2enmod rewrite deflate - $ sudo a2ensite koha - $ sudo apache2ctl restart - - Note: you may still see the usual Apache default site if your - VirtualHost configuration isn't correct. The command - "sudo a2dissite default" may be a quick fix, but may have - side-effects. See the Apache HTTPD manual section on - virtual hosts for full instructions. - - -5. Configure and start Zebra - - This process send responses to search requests sent by Koha or - Z39.50/SRU/SRW clients. - - NOTE: the user you run Zebra as will be the only user with - write permission on the Zebra index; in development mode, - you may wish to use your system user. - - -5.1 Zebra Search Server - - Set the zebra daemon to run on start: - $ sudo ln -s /usr/share/koha/bin/koha-zebra-ctl.sh /etc/init.d/koha-zebra-daemon - $ sudo update-rc.d koha-zebra-daemon defaults - $ sudo /etc/init.d/koha-zebra-daemon start - - NOTE: change the path to koha-zebra-ctl.sh to match your setup - if not using the default. - - -5.2 Zebra Indexer - - There are two ways to do this. ONLY DO ONE! DO NOT DO BOTH! - - Option 1: - You can configure zebra-indexing as an background daemon, see - http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra - - Option 2: - - Add an entry in Koha user crontab to scheduled - added/updated/deleted records indexing by Zebra with this - command: - /misc/migration_tools/rebuild_zebra -z -b -a - - See check misc/cronjobs/crontab.example for usage examples. - - NOTE: This job should be setup under the kohauser - (the default is 'koha'). - - -6. Run the Web Installer, populate the database, - initial configuration of settings - - The hope is that your server is accessible via a nice browser - somewhere. If not, install lynx to finish the web install on - your Koha server: - $ sudo apt-get install lynx - - Point your browser to http://:8080/ - - If you installed lynx, and are using defaults, it might be - something like: - $ lynx http://127.0.1.1:8080/ - - It should redirect you to the Web Installer where you can - continue the setup. You can install the sample data for - libraries, patrons, etc. via the Web Installer - - -7. Install additional languages - - In your install directory you can run this commands to have - your Koha setup translated to your language: - - Set your environment variables: - $ export KOHA_CONF=/etc/koha/sites/koha/koha-conf.xml - $ export PERL5LIB=/usr/share/koha/lib/ - - NOTE: the path to koha-conf.xml may be different depending on - your installation choices. - - Run the translator script: - $ cd /usr/share/koha/misc/translator - $ perl translate install - - must be one of the included in the - misc/translator/po directory. - - NOTE: You can add as many languages as you need. In order to - use them you will have to enable them first in the - 'I18N/L10N' section of the Koha preferences. - - -8. What next? - - NOTE: You can use the 'Stage MARC records for import' from the - Tools area of Koha's Staff Client to import a batch of - MARC records, rather than these instructions. - - Once the installer has completed, you can import and index MARC - records from the command line thusly: - $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml - NOTE: use the correct path to your koha-conf.xml - -8.1 Import - - Bibliographic data in MARC21 format: - $ misc/migration_tools/bulkmarcimport.pl -file /path/to/marc.iso2709 - - Authority data in MARC21 format: - $ misc/migration_tools/bulkauthimport.pl -file /path/to/auth.iso2709 - -8.2 Fast Index: - - NOTE: This script must be run as the kohauser otherwise - permission errors and indexing problems will follow. - (the default is 'koha' -- see step 3). - - $ misc/migration_tools/rebuild_zebra.pl -b -w - - Once the indexing has completed, you will be able to search for - records in your system. - - -8.3 Public Z39.50/SRU server - - To enable public Z39.50/SRU servers, you'll need to edit your - koha-conf.xml and change the options to listen on a - TCP port; then restart the zebra daemon. - - -UPGRADE -================================================================= - - 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. - - -1. Install new Perl dependencies - - If you are upgrading from a previous installation of Koha 3.x, - you can use the following to identify new Perl dependencies: - $ ./koha_perl_deps.pl -u -m - - Install any missing modules using the instructions on sections - 1.6 and 1.7. - - -2. Upgrade Koha - - $ perl Makefile.PL --prev-install-log /path/to/koha-install-log - $ make - $ make test - $ sudo make upgrade - - -3. Pre-3.4 upgrades - - Koha 3.4.x or later no longer stores items in biblio records so - if you are upgrading from an older version as part of the - upgrade you will need to do the following two steps, they can - take a long time (several hours) to complete for large - databases: - $ misc/maintenance/remove_items_from_biblioitems.pl --run - $ misc/migration_tools/rebuild_zebra.pl -b -r - - -Uninstall Instructions -================================================================= - -1. Stop Services: - - Firstly, remove the apache website: - $ sudo a2dissite koha - $ sudo rm /etc/apache2/sites-available/koha - $ sudo apache2ctl restart - - Next, remove the koha-zebra-daemon: - $ sudo update-rc.d koha-zebra-daemon remove - $ sudo rm /etc/init.d/koha-zebra-daemon - - -2a. Remove Database: - - Remember the , - need to be substituted on the following commands: - $ mysql -u -p - mysql> drop database ; - - -2b. Remove Indexes: - - To help determine what should be substituted with, - run the following command: - $ sudo find / -name "zebra-biblios.cfg" - /etc/koha/zebradb/zebra-biblios.cfg - /home/user/koha-3.08.03/etc/zebradb/zebra-biblios.cfg - /home/user/koha-3.08.03/blib/ZEBRA_CONF_DIR/zebra-biblios.cfg - There may be three copies, two of which will likely be in the - user account that installed Koha. In this example, our - is '/etc/koha'. - - Once you know the value of prefix, run these commands - substituting in the correct value: - $ zebraidx -c /zebradb/zebra-biblios.cfg -g iso2709 -d biblios init - $ zebraidx -c /zebradb/zebra-authorities.cfg -g iso2709 -d authorities init - - -3. Remove Koha Install Directories and Configuration Files - Don't forget about any crontab entries - - -Tested on the following operating environments -================================================================= - - Ubuntu Precise Pangolin 12.04 - - -Installer Bug reports -================================================================= - Please log any installer bug reports at - http://bugs.koha-community.org - - -Other Notes -================================================================= -This file is part of Koha - -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 2 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, write to the Free Software Foundation: - Free Software Foundation - 51 Franklin Street, Fifth Floor - Boston, MA 02110-1301 - USA -Or visit their website: http://www.fsf.org/ diff --git a/INSTALL.ubuntu.lucid b/INSTALL.ubuntu.lucid deleted file mode 100644 index 0003e16f3e..0000000000 --- a/INSTALL.ubuntu.lucid +++ /dev/null @@ -1,380 +0,0 @@ -============================= -Installation Guide for Installing Koha on Ubuntu Lucid Lynx (10.04 LTS) with MySQL 5 -============================= - -Copyright (C) 2007, 2008 LibLime (http://liblime.com) -Some parts copyright 2010 Chris Nighswonger - -Original author: Joshua Ferraro -Modified for Ubuntu by: Chris Nighswonger (cnighswonger AT foundations DOT edu) - -Feedback/bug reports: Koha Developer's List: -http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel - -This document last modified: 20 Marchp 2012 - -Installation Instructions -============================= - -All commands can be performed as a system user with sudo privileges, -as indicated or by running the command directly as root. - -1. Prepare System and Install Dependencies - -1.1 Install Ubuntu Lucid Lynx via CD - -See http://www.ubuntu.com/getubuntu/download - -1.2 Set up your locale - -Your locale should be set to UTF-8, as should Apache2 and MySQL 5. -This step is VERY IMPORTANT for a UNICODE compliant system. Please -read over the following document carefully: - -http://wiki.koha-community.org/wiki/Encoding_and_Character_Sets_in_Koha - -You can verify your system locale by typing the following command: - - $ locale - -IMPORTANT: You _MUST_ follow all the steps outlined there for - Apache2, MySQL 5, etc. BEFORE you install Koha. - -1.3 Get Koha - -1.3.1 Option A: Download Koha via Git (optional) - - $ sudo apt-get install git-core git-email - $ git clone git://git.koha-community.org/koha.git kohaclone - $ cd kohaclone - $ git checkout -b myinstall origin - -Note: for more information about Git, please see the Koha Git Usage Guide: - - http://wiki.koha-community.org/wiki/Version_Control_Using_Git - -1.3.2 Option B: Download Koha from http://download.koha-community.org - - $ wget http://download.koha-community.org/koha-3.02.00.tar.gz - ( Note: use the latest stable version) - -1.4 Install additional Ubuntu dependencies - -IMPORTANT: You should only use CPAN for Perl dependencies which are NOT - available from the package maintainer. You have been warned! - -Using the ubuntu.packages file included in the Koha source tree, -run the following: - - $ sudo dpkg --set-selections < install_misc/ubuntu.packages - -Now start dselect (you may need to 'sudo apt-get install dselect'): - - $ sudo dselect - -Choose [I]nstall and accept packages to be installed (hit return) - -(may take a while) - -Choose [C]onfigure, [R]emove and [Q]uit until dselect has completed. - -Note: If you are installing on an older version of Ubuntu, not all of the - packages listed in ubuntu.packages may be available as packages. You - will want to verify which ones are installed and which ones not. - This can be done by running the following command: - - $ install_misc/ubuntu-pkg-check.sh | grep none - -When tracking down any "(none)" results, note that sometimes Ubuntu does the -right thing and installs a later, differently named version of the package in -place. To see if this is happening, it is useful to run a command like: - - $ dpkg --get-selections | grep [base_package_name] - -1.5 Install Perl dependencies that aren't packaged into Ubuntu Lucid Lynx -sources - -Run the following command: - - $ sudo cpan HTTP::OAI Locale::Currency::Format Memoize::Memcached \ - PDF::API2::Simple Storable Text::CSV::Encoded CHI \ - CHI::Driver::Memcached - -Note: you may need to run CPAN initialization if you've not run cpan -before: - - /etc/perl/CPAN/Config.pm initialized. - - CPAN is the world-wide archive of perl resources. It consists of about - 100 sites that all replicate the same contents all around the globe. - Many countries have at least one CPAN site already. The resources - found on CPAN are easily accessible with the CPAN.pm module. If you - want to use CPAN.pm, you have to configure it properly. - - If you do not want to enter a dialog now, you can answer 'no' to this - question and I'll try to autoconfigure. (Note: you can revisit this - dialog anytime later by typing 'o conf init' at the cpan prompt.) - - Are you ready for manual configuration? [yes] - -When the configuration is completed CPAN will install the Perl modules. - -2. Configuration of dependencies - -2.1 Update root MySQL password (if dselect didn't do it for you already) - - $ sudo mysqladmin password - -2.2 Create the Koha database - - Create the database and user with associated privileges: - - $ mysqladmin -uroot -p create - $ mysql -uroot -p - - Welcome to the MySQL monitor. Commands end with ; or \g. - Your MySQL connection id is 22 - Server version: 5.0.32-Debian_7etch3-log Debian etch distribution - - Type 'help;' or '\h' for help. Type '\c' to clear the buffer. - - mysql> grant all on .* to ''@'localhost' identified by ''; - Query OK, 0 rows affected (0.00 sec) - - mysql> flush privileges; - Query OK, 0 rows affected (0.00 sec) - - mysql> quit - -2.3 Test your SAX Parser and correct where necessary - - You must be sure you're using the XML::LibXML SAX parser, not Expat or - PurePerl, both of which have outstanding bugs with pre-composed - characters. You can test your SAX parser by running: - - $ cd koha - $ misc/sax_parser_print.pl - - You should see something like:: - - XML::LibXML::SAX::Parser=HASH(0x81fe220) - - If you're using PurePerl or Expat, you'll need to edit your - ini file, typically located at: - - /etc/perl/XML/SAX/ParserDetails.ini - - You will need to move the entire section for '[XML::LibXML::SAX::Parser]' - to the bottom of the ini file. - -3. Run the Koha installer - - $ perl Makefile.PL - ( answer questions ) - $ make - $ make test - $ sudo make install - -4. Configure and start Apache - $ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha - (note that the path to koha-httpd.conf may be different depending on your - installation choices) - -Add the following lines to /etc/apache2/ports.conf: - - Listen 80 - Listen 8080 - -If not running named virtual hosts (The default koha installation does not use -named virtual hosts.), comment out the following line: - - NameVirtualHost *:80 - -Run the following commands: - - $ sudo a2enmod rewrite deflate - $ sudo a2ensite koha - $ sudo apache2ctl restart - -Note: you may still see the usual Apache default site if your VirtualHost -configuration isn't correct. The command "sudo a2dissite default" may be a -quick fix, but may have side-effects. See the Apache HTTPD manual section on -virtual hosts for full instructions. - -5. Configure and start Zebra - -Note: it's recommended that you daemonize the Zebra process and add it to your -startup profile. For a non-production test/development installation, running -Zebra from the command line can be useful. Pick from the two available options -below, or roll your own :-) - -Note: it's also recommended that you create a Koha system user, which you will -have specified during the install process. Alternatively, Zebra can be -configured to run as the root user. - -To add a user do: - - $ sudo adduser koha - -Option 1: run the Zebra processes from the command line: - -5.1.1 Zebra Search Server - -This process send responses to search requests sent by Koha or -Z39.50/SRU/SRW clients. - - $ sudo -u ${KOHA_USER} zebrasrv -f /etc/koha/koha-conf.xml - (note that the path to koha-conf.xml may be different depending on your - installation choices) - -Note: the user you run Zebra as will be the only user with write permission - on the Zebra index; in development mode, you may wish to use your - system user. - -5.1.2 Zebra Indexer - -Added/updated/deleted records in Koha MySQL database must be indexed -into Zebra. A specific script must be launched each time a bibliographic -or an authority record is edited. - - $ sudo -u ${KOHA_USER} misc/migration_tools/rebuild_zebra -z -b -a - NOTE: This script should be run as the kohauser (the default is 'koha'). - -Option 2: run the Zebra process as a daemon, and add to startup process: - -Note that references to $SCRIPT_DIR refer to the directory where -Koha's command-line scripts are installed, e.g., /usr/share/koha/bin. - -5.2.1 Zebra Search Server - - $ sudo ln -s ${SCRIPT_DIR}/koha-zebra-ctl.sh /etc/init.d/koha-zebra-daemon - (Note: ${SCRIPT_DIR} is /usr/share/koha/bin/ by default in a standard install) - $ sudo update-rc.d koha-zebra-daemon defaults - ( Note: see man chkconfig(8) on other distros ) - - $ sudo ${SCRIPT_DIR}/koha-zebra-ctl.sh start - -5.2.2 Zebra Indexer - -Add an entry in Koha user crontab to scheduled added/updated/deleted records -indexing by Zebra with this command: - - /misc/migration_tools/rebuild_zebra -z -b -a - -See check misc/cronjobs/crontab.example for usage examples. -NOTE: This job should be setup under the kohauser (the default is 'koha'). - -You can also configure zebra-indexing as an background daemon, see http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra - -6. Run the Web Installer, populate the database, initial configuration of settings - - Point your browser to http://:8080/ - - It should redirect you to the Web Installer where you can continue the setup. - You can install the sample data for libraries, patrons, etc. via the Web Installer - -7. What next? - - Once the installer has completed, you can import and index MARC records from the - command line thusly (Note: you can also use the 'Stage MARC records for import' from - the Tools area of Koha's Staff Client to import a batch of MARC records): - - $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml - (note: use the correct path to your koha-conf.xml) - -7.1 Import: - Bibliographic data in MARC21 format - $ misc/migration_tools/bulkmarcimport.pl -file /path/to/marc.iso2709 - Authority data in MARC21 format - $ misc/migration_tools/bulkauthimport.pl -file /path/to/auth.iso2709 - -7.2 Fast Index: - $ misc/migration_tools/rebuild_zebra.pl -b -w - - Once the indexing has completed, you will be able to search for records in your system. - NOTE: This script should be run as the kohauser (the default is 'koha'). - -7.3 Schedule regular index updates - - You need to run rebuild_zebra.pl -b -a -z as a regular cron job in orde to pick up new bibs - and items as you add them. Check misc/cronjobs/crontab.example for usage examples. See 7.0 above. - NOTE: This job should be setup under the kohauser (the default is 'koha'). - - You can also indexing in background, see 5.2.2 above - -7.4 To enable public Z39.50/SRU servers, you'll need to edit your koha-conf.xml and - change the options to listen on a TCP port; then restart the zebra daemon. - -UPGRADE -======= -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. - -If you are upgrading from a previous installation of Koha 3.x, you can -use the following: - - ./koha_perl_deps.pl -u -m # to identify new Perl dependencies - -Install any missing modules -IMPORTANT: Koha 3.6.x uses Template::Toolkit, this must be installed -before the webinstaller can run - - sudo apt-get install libtemplate-perl - -Koha 3.4.x or later no longer stores items in biblio records so -if you are upgrading from an older version as part of the -upgrade you will need to do the following two steps, they can take a -long time (several hours) to complete for large databases - - misc/maintenance/remove_items_from_biblioitems.pl --run - misc/migration_tools/rebuild_zebra.pl -b -r - -Uninstall Instructions -============================= -1) Stop Services: - $ sudo a2dissite koha - $ sudo rm /etc/apache2/sites-available/koha - $ sudo apache2ctl restart - - $ sudo update-rc.d koha-zebra-daemon remove - $ sudo rm /etc/init.d/koha-zebra-daemon - -2) Remove Database and Indexes - - # MySQL - $ mysql -u -p - > drop database koha; - - # Zebra Indexes - $ zebraidx -c /etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init - $ zebraidx -c /etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init - -3) Remove Koha Install Directories and Configuration Files - Don't forget about any crontab entries - -Tested on the following operating environments -============================================== -- Ubuntu Jaunty Jackalope 9.04 - -Installer Bug reports -===================== -Please log any installer bug reports at http://bugs.koha-community.org - -Other Notes -===================== -This file is part of Koha - -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 2 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, write to the Free Software Foundation, Inc., -51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. -- 2.39.5