1 =============================
2 Installation Guide for Installing Koha on Ubuntu Jaunty (9.04) with MySQL 5
3 =============================
5 Copyright (C) 2007, 2008 LibLime (http://liblime.com)
7 Original author: Joshua Ferraro (jmf AT liblime DOT com)
8 Modified for Ubuntu by: Chris Nighswonger (cnighswonger AT foundations DOT edu)
10 Feedback/bug reports: Koha Developer's List:
11 http://lists.koha.org/mailman/listinfo/koha-devel
13 This document last modified: 22 June 2009
15 Installation Instructions
16 =============================
18 All commands can be performed as a system user with sudo privileges,
19 as indicated or by running the command directly as root.
21 1. Prepare System and Install Dependencies
23 1.1 Install Ubuntu Jaunty via CD
25 See http://www.ubuntu.com/getubuntu/download
27 1.2 Set up your locale
29 Your locale should be set to UTF-8, as should Apache2 and MySQL 5.
30 This step is VERY IMPORTANT for a UNICODE compliant system. Please
31 read over the following document carefully:
33 http://wiki.koha.org/doku.php?id=encodingscratchpad
35 You can verify your system locale by typing the following command:
39 IMPORTANT: You _MUST_ follow all the steps outlined there for
40 Apache2, MySQL 5, etc. BEFORE you install Koha.
42 1.3 Install the Yaz and Zebra packages
44 Add Indexdata repository to your sources
46 $ sudo gedit /etc/apt/sources.list
48 Add those lines at the end of the file
50 # IndexData Repository
51 deb http://ftp.indexdata.dk/pub/ubuntu/ jaunty main
53 where jaunty is the name of your ubuntu version
57 Add Indexdata Key in order to be able to check signatures
60 $ wget http://ftp.indexdata.dk/debian/indexdata.asc
61 $ sudo apt-key add indexdata.asc
64 Run the following command to update your system:
67 $ sudo apt-get install yaz idzebra-2.0 idzebra-2.0-doc
71 1.4.1 Option A: Download Koha via Git (optional)
73 $ sudo apt-get install git-core git-email
74 $ git clone git://git.koha.org/pub/scm/koha.git kohaclone
76 $ git checkout -b myinstall origin
78 Note: for more information about Git, please see the Koha Git Usage Guide:
80 http://wiki.koha.org/doku.php?id=en:development:git_usage
82 1.4.2 Option B: Download Koha from http://download.koha.org
84 $ wget http://download.koha.org/koha-3.00.02.tar.gz
85 ( Note: use the latest stable version)
87 1.5 Install additional Ubuntu dependencies
89 IMPORTANT: You should only use CPAN for Perl dependencies which are NOT
90 available from the package maintainer. You have been warned!
92 Using the ubuntu.packages file included in the Koha source tree,
95 $ sudo dpkg --set-selections < install_misc/ubuntu.packages
97 Now start dselect (you may need to 'sudo apt-get install dselect'):
101 Choose [I]nstall and accept packages to be installed (hit return)
105 Choose [C]onfigure, [R]emove and [Q]uit until dselect has completed.
107 1.6 Install Perl dependencies that aren't packaged into Ubuntu Jaunty
110 Run the following command:
112 $ sudo cpan MARC::Crosswalk::DublinCore GD GD::Barcode::UPCE Email::Date \
113 HTML::Scrubber Algorithm::CheckDigits::M43_001 Biblio::EndnoteStyle \
116 Note: you may need to run CPAN initialization if you've not run cpan
119 /etc/perl/CPAN/Config.pm initialized.
121 CPAN is the world-wide archive of perl resources. It consists of about
122 100 sites that all replicate the same contents all around the globe.
123 Many countries have at least one CPAN site already. The resources
124 found on CPAN are easily accessible with the CPAN.pm module. If you
125 want to use CPAN.pm, you have to configure it properly.
127 If you do not want to enter a dialog now, you can answer 'no' to this
128 question and I'll try to autoconfigure. (Note: you can revisit this
129 dialog anytime later by typing 'o conf init' at the cpan prompt.)
131 Are you ready for manual configuration? [yes]
133 When the configuration is completed CPAN will install the Perl modules.
135 2. Configuration of dependencies
137 2.1 Update root MySQL password (if dselect didn't do it for you already)
139 $ sudo mysqladmin password <password>
141 2.2 Create the Koha database
143 Create the database and user with associated privileges:
145 $ mysqladmin -uroot -p<password> create <kohadatabasename>
146 $ mysql -uroot -p<password>
148 Welcome to the MySQL monitor. Commands end with ; or \g.
149 Your MySQL connection id is 22
150 Server version: 5.0.32-Debian_7etch3-log Debian etch distribution
152 Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
154 mysql> grant all on <kohadatabasename>.* to '<kohadatabaseuser>'@'localhost' identified by '<kohadatabaseuserpassword>';
155 Query OK, 0 rows affected (0.00 sec)
157 mysql> flush privileges;
158 Query OK, 0 rows affected (0.00 sec)
162 2.3 Test your SAX Parser and correct where necessary
164 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:
167 $ misc/sax_parser_print.pl
169 You should see something like::
171 XML::LibXML::SAX::Parser=HASH(0x81fe220)
173 If you're using PurePerl or Expat, you'll need to edit your
174 ini file, typically located at:
176 /etc/perl/XML/SAX/ParserDetails.ini
178 2.4 Install DBD::mysql Perl module
180 In order to handle UTF-8 correctly, Koha requires at least version 4.004
181 of the DBD::mysql Perl module. However, Debian Etch has a stable package
182 only for version 3.0008, so it is necessary to install the module from CPAN.
183 DBD::mysql's test suite needs to use a MySQL 'test' DB which doesn't exist
184 anymore. So there are two options to install DBD::mysql:
186 (1) install without test suite,
187 (2) install with test suite requiring a test MySQL DB creation.
189 2.4.1 Install without test suite
191 Force install DBD::mysql:
194 cpan> force install DBD::mysql
196 2.4.2 Create test database in order to install DBD::mysql
198 Because of DBD::mysql's test suite, it is necessary to temporarily create a
199 test database and user:
201 $ mysql -uroot -p<password>
203 Create the database and user with associated privileges:
205 Welcome to the MySQL monitor. Commands end with ; or \g.
206 Your MySQL connection id is 22
207 Server version: 5.0.32-Debian_7etch3-log Debian etch distribution
209 Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
211 mysql> create database test;
212 Query OK, 1 row affected (0.00 sec)
214 mysql> grant all on test.* to 'test'@'localhost' identified by 'test';
215 Query OK, 0 rows affected (0.00 sec)
216 (test database, user, and password can be different if need be)
218 mysql> flush privileges;
219 Query OK, 0 rows affected (0.00 sec)
223 Next install DBD::mysql:
227 cpan> o conf makepl_arg
228 (get current value of this CPAN parameter)
230 cpan> o conf makepl_arg "--testdb=test --testuser=test --testpass=test"
232 cpan> install DBD::mysql
234 cpan> o conf makepl_arg ''
238 cpan> o conf makepl_arg '<old setting>'
240 (restore this setting so as to not interfere with future CPAN installs).
243 Finally, remove the test database:
245 $ mysql -uroot -p<password>
247 mysql> drop database test;
248 Query OK, 1 row affected (0.00 sec)
253 3. Run the Koha installer
261 4. Configure and start Apache
262 $ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha
263 (note that the path to koha-httpd.conf may be different depending on your
264 installation choices)
266 Add the following lines to /etc/apache2/ports.conf:
271 If not running named virtual hosts (The default koha installation does not use named virtual hosts.), comment out the following line:
275 Run the following commands:
277 $ sudo a2enmod rewrite
279 $ sudo apache2ctl restart
281 Note: you may still see the usual Apache default site if your VirtualHost
282 configuration isn't correct. The command "sudo a2dissite default" may be a
283 quick fix, but may have side-effects. See the Apache HTTPD manual section on
284 virtual hosts for full instructions.
286 5. Configure and start Zebra
288 Note: it's recommended that you daemonize the Zebra process and add it to your
289 startup profile. For a non-production test/development installation, running
290 Zebra from the command line can be useful. Pick from the two available options
291 below, or roll your own :-)
293 Note: it's also recommended that you create a Koha system user, which you will
294 have specified during the install process. Alternatively, Zebra can be
295 configured to run as the root user.
302 Option 1: run the Zebra processes from the command line:
305 $ sudo -u ${KOHA_USER} zebrasrv -f /etc/koha/koha-conf.xml
306 (note that the path to koha-conf.xml may be different depending on your
307 installation choices)
309 Note: the user you run Zebra as will be the only user with write permission
310 on the Zebra index; in development mode, you may wish to use your system
314 $ sudo -u ${KOHA_USER} misc/bin/zebraqueue_daemon.pl
316 Note: if you are running in this mode, you may wish to defer starting the
317 zebraqueue until you've run the web installer (see below).
319 Option 2: run the Zebra processes as daemons, and add to startup process:
321 Note that references to $SCRIPT_DIR refer to the directory where
322 Koha's command-line scripts are installed, e.g., /usr/share/koha/bin.
325 $ sudo ln -s ${SCRIPT_DIR}/koha-zebra-ctl.sh /etc/init.d/koha-zebra-daemon
326 (Note: ${SCRIPT_DIR} is /usr/share/koha/bin/ by default in a standard install)
327 $ sudo update-rc.d koha-zebra-daemon defaults
328 ( Note: see man chkconfig(8) on other distros )
330 $ sudo ${SCRIPT_DIR}/koha-zebra-ctl.sh start
333 $ sudo ln -s ${SCRIPT_DIR}/koha-zebraqueue-ctl.sh /etc/init.d/koha-zebraqueue-daemon
334 $ sudo update-rc.d koha-zebraqueue-daemon defaults
335 ( Note: see man chkconfig(8) on other distros )
337 $ sudo ${SCRIPT_DIR}/koha-zebraqueue-ctl.sh start
339 6. Run the Web Installer, populate the database, initial configuration of settings
341 Point your browser to http://<servername>:8080/
343 It should redirect you to the Web Installer where you can continue the setup.
344 You can install the sample data for libraries, patrons, etc. via the Web Installer
348 Once the installer has completed, you can import and index MARC records from the
349 command line thusly (Note: you can also use the 'Stage MARC records for import' from
350 the Tools area of Koha's Staff Client to import a batch of MARC records):
352 $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml
353 (note: use the correct path to your koha-conf.xml)
356 Bibliographic data in MARC21 format
357 $ misc/migration-tools/bulkmarcimport.pl -file /path/to/marc.iso2709
358 Authority data in MARC21 format
359 $ misc/migration-tools/bulkauthimport.pl -file /path/to/auth.iso2709
362 $ misc/migration-tools/rebuild_zebra.pl -b -w
364 Once the indexing has completed, you will be able to search for records in your
365 system. NOTE: if you don't run the Fast Index utility, and you have the index
366 updates scheduled as per 7.3 the indexing process will happen in the background,
367 but it will be orders of magnitude slower.
369 7.3 Schedule regular index updates
370 run rebuild_zebra.pl -b -a -z as a regular cron job, check misc/cronjobs/crontab.example
373 7.4 To enable public Z39.50/SRU servers, you'll need to edit your koha-conf.xml and
374 change the <listen> options to listen on a TCP port; then restart the zebra daemon.
378 If you are upgrading from a previous installation of Koha 3, you can
381 perl Makefile.PL --prev-install-log /path/to/koha-install-log
386 Uninstall Instructions
387 =============================
389 $ sudo a2dissite koha
390 $ sudo rm /etc/apache2/sites-available/koha
391 $ sudo apache2ctl restart
393 $ sudo update-rc.d koha-zebra-daemon remove
394 $ sudo rm /etc/init.d/koha-zebra-daemon
396 2) Remove Database and Indexes
399 $ mysql -u<kohauser> -p<kohapassword>
400 > drop database koha;
403 $ zebraidx -c <prefix>/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
404 $ zebraidx -c <prefix>/etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
406 3) Remove Koha Install Directories and Configuration Files
407 Don't forget about any crontab entries
409 Tested on the following operating environments
410 ==============================================
411 - Ubuntu Jaunty Jackalope 9.04
413 Installer Bug reports
414 =====================
415 Please log any installer bug reports at http://bugs.koha.org
418 =====================
419 This file is part of Koha
421 Koha is free software; you can redistribute it and/or modify it under the
422 terms of the GNU General Public License as published by the Free Software
423 Foundation; either version 2 of the License, or (at your option) any later
426 Koha is distributed in the hope that it will be useful, but WITHOUT ANY
427 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
428 A PARTICULAR PURPOSE. See the GNU General Public License for more details.
429 You should have received a copy of the GNU General Public License along with
430 Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
431 Suite 330, Boston, MA 02111-1307 USA