-=============================
-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 <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<password> create <kohadatabasename>
- $ mysql -uroot -p<password>
+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 <kohadatabasename>.* to '<kohadatabaseuser>'@'localhost' identified by '<kohadatabaseuserpassword>';
- 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<password>
+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 '<old setting>'
+ 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<password>
+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
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+<VirtualHost *:80>
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-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
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+<VirtualHost *:8080>
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- 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.
- <path/to/koha>/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://<servername>: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 <listen> 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<kohauser> -p<kohapassword>
- > 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 <prefix>/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
- $ zebraidx -c <prefix>/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 <http://www.gnu.org/licenses>.
+++ /dev/null
-=================================================================
-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 <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:
- <path/to/koha>/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://<servername>: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 <language-code>
-
- <language-code> 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 <listen> 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 <kohauser>, <kohapassword, and <kohadatabasename>
- need to be substituted on the following commands:
- $ mysql -u<kohauser> -p<kohapassword>
- mysql> drop database <kohadatabasename>;
-
-
-2b. Remove Indexes:
-
- To help determine what <prefix> 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 <prefix>
- is '/etc/koha'.
-
- Once you know the value of prefix, run these commands
- substituting in the correct value:
- $ zebraidx -c <prefix>/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
- $ zebraidx -c <prefix>/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/
+++ /dev/null
-=============================
-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 <password>
-
-2.2 Create the Koha database
-
- Create the database and user with associated privileges:
-
- $ mysqladmin -uroot -p<password> create <kohadatabasename>
- $ mysql -uroot -p<password>
-
- 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 <kohadatabasename>.* to '<kohadatabaseuser>'@'localhost' identified by '<kohadatabaseuserpassword>';
- 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:
-
- <path/to/koha>/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://<servername>: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 <listen> 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<kohauser> -p<kohapassword>
- > drop database koha;
-
- # Zebra Indexes
- $ zebraidx -c <prefix>/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
- $ zebraidx -c <prefix>/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.
projects / koha_fer / commitdiff