bug 4151: fix migration_tools typo
[wip/koha-chris_n.git] / INSTALL.ubuntu
1 =============================
2 Installation Guide for Installing Koha on Ubuntu Jaunty (9.04) with MySQL 5
3 =============================
4
5 Copyright (C) 2007, 2008 LibLime (http://liblime.com)
6
7 Original author: Joshua Ferraro (jmf AT liblime DOT com)
8 Modified for Ubuntu by: Chris Nighswonger (cnighswonger AT foundations DOT edu)
9
10 Feedback/bug reports: Koha Developer's List:
11 http://lists.koha.org/mailman/listinfo/koha-devel
12
13 This document last modified: 22 June 2009
14
15 Installation Instructions
16 =============================
17
18 All commands can be performed as a system user with sudo privileges,
19 as indicated or by running the command directly as root.
20
21 1. Prepare System and Install Dependencies
22
23 1.1 Install Ubuntu Jaunty via CD
24
25 See http://www.ubuntu.com/getubuntu/download
26
27 1.2 Set up your locale
28
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:
32
33 http://wiki.koha.org/doku.php?id=encodingscratchpad
34
35 You can verify your system locale by typing the following command:
36
37     $ locale
38
39 IMPORTANT:  You _MUST_ follow all the steps outlined there for
40             Apache2, MySQL 5, etc. BEFORE you install Koha.
41
42 1.3 Install the Yaz and Zebra packages
43
44 Run the following command to update your system:
45
46     $ sudo apt-get update
47     $ sudo apt-get install yaz idzebra-2.0 idzebra-2.0-doc
48
49 1.4 Get Koha
50
51 1.4.1 Option A: Download Koha via Git (optional)
52
53     $ sudo apt-get install git-core git-email
54     $ git clone git://git.koha.org/pub/scm/koha.git kohaclone
55     $ cd kohaclone
56     $ git checkout -b myinstall origin
57
58 Note: for more information about Git, please see the Koha Git Usage Guide:
59
60     http://wiki.koha.org/doku.php?id=en:development:git_usage
61
62 1.4.2 Option B: Download Koha from http://download.koha.org
63
64     $ wget http://download.koha.org/koha-3.00.02.tar.gz
65     ( Note: use the latest stable version)
66
67 1.5 Install additional Ubuntu dependencies
68
69 IMPORTANT:  You should only use CPAN for Perl dependencies which are NOT
70             available from the package maintainer. You have been warned!
71
72 Using the ubuntu.packages file included in the Koha source tree,
73 run the following:
74
75     $ sudo dpkg --set-selections < install_misc/ubuntu.packages
76
77 Now start dselect (you may need to 'sudo apt-get install dselect'):
78
79     $ sudo dselect
80
81 Choose [I]nstall and accept packages to be installed (hit return)
82
83 (may take a while)
84
85 Choose [C]onfigure, [R]emove and [Q]uit until dselect has completed.
86
87 1.6 Install Perl dependencies that aren't packaged into Ubuntu Jaunty
88 sources
89
90 Run the following command:
91
92     $ sudo cpan MARC::Crosswalk::DublinCore GD GD::Barcode::UPCE Email::Date \
93                 HTML::Scrubber Algorithm::CheckDigits::M43_001 Biblio::EndnoteStyle \
94                 Locale::Currency::Format
95
96 Note: you may need to run CPAN initialization if you've not run cpan
97 before:
98
99     /etc/perl/CPAN/Config.pm initialized.
100
101     CPAN is the world-wide archive of perl resources. It consists of about
102     100 sites that all replicate the same contents all around the globe.
103     Many countries have at least one CPAN site already. The resources
104     found on CPAN are easily accessible with the CPAN.pm module. If you
105     want to use CPAN.pm, you have to configure it properly.
106
107     If you do not want to enter a dialog now, you can answer 'no' to this
108     question and I'll try to autoconfigure. (Note: you can revisit this
109     dialog anytime later by typing 'o conf init' at the cpan prompt.)
110
111     Are you ready for manual configuration? [yes]
112
113 When the configuration is completed CPAN will install the Perl modules.
114
115 2. Configuration of dependencies
116
117 2.1 Update root MySQL password (if dselect didn't do it for you already)
118
119     $ sudo mysqladmin password <password>
120
121 2.2 Create the Koha database
122
123     Create the database and user with associated privileges:
124
125     $ mysqladmin -uroot -p<password> create <kohadatabasename>
126     $ mysql -uroot -p<password>
127
128     Welcome to the MySQL monitor.  Commands end with ; or \g.
129     Your MySQL connection id is 22
130     Server version: 5.0.32-Debian_7etch3-log Debian etch distribution
131
132     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
133
134     mysql> grant all on <kohadatabasename>.* to '<kohadatabaseuser>'@'localhost' identified by '<kohadatabaseuserpassword>';
135     Query OK, 0 rows affected (0.00 sec)
136
137     mysql> flush privileges;
138     Query OK, 0 rows affected (0.00 sec)
139
140     mysql> quit
141
142 2.3 Test your SAX Parser and correct where necessary
143
144     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:
145
146     $ cd koha
147     $ misc/sax_parser_print.pl
148
149     You should see something like::
150
151     XML::LibXML::SAX::Parser=HASH(0x81fe220)
152
153     If you're using PurePerl or Expat, you'll need to edit your
154     ini file, typically located at:
155
156     /etc/perl/XML/SAX/ParserDetails.ini
157
158 2.4 Install DBD::mysql Perl module
159
160 In order to handle UTF-8 correctly, Koha requires at least version 4.004
161 of the DBD::mysql Perl module. However, Debian Etch has a stable package
162 only for version 3.0008, so it is necessary to install the module  from CPAN.
163 DBD::mysql's test suite needs to use a MySQL 'test' DB which doesn't exist
164 anymore. So there are two options to install DBD::mysql:
165
166   (1) install without test suite,
167   (2) install with test suite requiring a test MySQL DB creation.
168
169 2.4.1 Install without test suite
170
171 Force install DBD::mysql:
172
173     $ sudo cpan
174     cpan> force install DBD::mysql
175
176 2.4.2 Create test database in order to install DBD::mysql
177
178 Because of DBD::mysql's test suite, it is necessary to temporarily create a
179 test database and user:
180
181     $ mysql -uroot -p<password>
182
183     Create the database and user with associated privileges:
184
185     Welcome to the MySQL monitor.  Commands end with ; or \g.
186     Your MySQL connection id is 22
187     Server version: 5.0.32-Debian_7etch3-log Debian etch distribution
188
189     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
190
191     mysql> create database test;
192     Query OK, 1 row affected (0.00 sec)
193
194     mysql> grant all on test.* to 'test'@'localhost' identified by 'test';
195     Query OK, 0 rows affected (0.00 sec)
196     (test database, user, and password can be different if need be)
197
198     mysql> flush privileges;
199     Query OK, 0 rows affected (0.00 sec)
200
201     mysql> quit
202
203 Next install DBD::mysql:
204
205     $ sudo cpan
206
207     cpan> o conf makepl_arg
208     (get current value of this CPAN parameter)
209
210     cpan> o conf makepl_arg "--testdb=test --testuser=test --testpass=test"
211
212     cpan> install DBD::mysql
213
214     cpan> o conf makepl_arg ''
215
216     OR
217
218     cpan> o conf makepl_arg '<old setting>'
219
220     (restore this setting so as to not interfere with future CPAN installs).
221
222
223 Finally, remove the test database:
224
225     $ mysql -uroot -p<password>
226
227     mysql> drop database test;
228     Query OK, 1 row affected (0.00 sec)
229
230     mysql> exit
231     Bye
232
233 3. Run the Koha installer
234
235     $ perl Makefile.PL
236     ( answer questions )
237     $ make
238     $ make test
239     $ sudo make install
240
241 4. Configure and start Apache
242     $ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha
243     (note that the path to koha-httpd.conf may be different depending on your
244     installation choices)
245
246 Add the following lines to /etc/apache2/ports.conf:
247
248     Listen 80
249     Listen 8080
250
251 If not running named virtual hosts (The default koha installation does not use named virtual hosts.), comment out the following line:
252
253     NameVirtualHost *:80
254
255 Run the following commands:
256
257     $ sudo a2enmod rewrite
258     $ sudo a2ensite koha
259     $ sudo apache2ctl restart
260
261 Note: you may still see the usual Apache default site if your VirtualHost
262 configuration isn't correct.  The command "sudo a2dissite default" may be a
263 quick fix, but may have side-effects.  See the Apache HTTPD manual section on
264 virtual hosts for full instructions.
265
266 5. Configure and start Zebra
267
268 Note: it's recommended that you daemonize the Zebra process and add it to your
269 startup profile. For a non-production test/development installation, running
270 Zebra from the command line can be useful. Pick from the two available options
271 below, or roll your own :-)
272
273 Note: it's also recommended that you create a Koha system user, which you will
274 have specified during the install process. Alternatively, Zebra can be
275 configured to run as the root user.
276
277 To add a user do:
278
279         $ sudo adduser koha
280
281
282 Option 1: run the Zebra processes from the command line:
283
284     Zebra Server:
285     $ sudo -u ${KOHA_USER} zebrasrv -f /etc/koha/koha-conf.xml
286     (note that the path to koha-conf.xml may be different depending on your
287     installation choices)
288
289     Note: the user you run Zebra as will be the only user with write permission
290     on the Zebra index; in development mode, you may wish to use your system
291     user.
292
293     Zebraqueue Daemon:
294     $ sudo -u ${KOHA_USER} misc/bin/zebraqueue_daemon.pl
295
296     Note: if you are running in this mode, you may wish to defer starting the
297     zebraqueue until you've run the web installer (see below).
298
299 Option 2: run the Zebra processes as daemons, and add to startup process:
300
301 Note that references to $SCRIPT_DIR refer to the directory where
302 Koha's command-line scripts are installed, e.g., /usr/share/koha/bin.
303
304     Zebra Server:
305     $ sudo ln -s ${SCRIPT_DIR}/koha-zebra-ctl.sh  /etc/init.d/koha-zebra-daemon
306     (Note: ${SCRIPT_DIR} is /usr/share/koha/bin/ by default in a standard install)
307     $ sudo update-rc.d koha-zebra-daemon defaults
308     ( Note: see man chkconfig(8) on other distros )
309
310     $ sudo ${SCRIPT_DIR}/koha-zebra-ctl.sh start
311
312     Zebraqueue Daemon:
313     $ sudo ln -s ${SCRIPT_DIR}/koha-zebraqueue-ctl.sh  /etc/init.d/koha-zebraqueue-daemon
314     $ sudo update-rc.d koha-zebraqueue-daemon defaults
315     ( Note: see man chkconfig(8) on other distros )
316
317     $ sudo ${SCRIPT_DIR}/koha-zebraqueue-ctl.sh start
318
319 6. Run the Web Installer, populate the database, initial configuration of settings
320
321     Point your browser to http://<servername>:8080/
322
323     It should redirect you to the Web Installer where you can continue the setup.
324     You can install the sample data for libraries, patrons, etc. via the Web Installer
325
326 7. What next?
327
328     Once the installer has completed, you can import and index MARC records from the
329     command line thusly (Note: you can also use the 'Stage MARC records for import' from
330     the Tools area of Koha's Staff Client to import a batch of MARC records):
331
332     $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml
333       (note: use the correct path to your koha-conf.xml)
334
335 7.1 Import:
336     Bibliographic data in MARC21 format
337     $ misc/migration_tools/bulkmarcimport.pl -file /path/to/marc.iso2709
338     Authority data in MARC21 format
339         $ misc/migration_tools/bulkauthimport.pl -file /path/to/auth.iso2709
340
341 7.2 Fast Index:
342     $ misc/migration_tools/rebuild_zebra.pl -b -w
343
344     Once the indexing has completed, you will be able to search for records in your
345     system. NOTE: if you don't run the Fast Index utility, and you have the index
346         updates scheduled as per 7.3 the indexing process will happen in the background,
347         but it will be orders of magnitude slower.
348
349 7.3 Schedule regular index updates
350     run rebuild_zebra.pl -b -a -z as a regular cron job, check misc/cronjobs/crontab.example
351         for usage examples
352
353 7.4 To enable public Z39.50/SRU servers, you'll need to edit your koha-conf.xml and
354     change the <listen> options to listen on a TCP port; then restart the zebra daemon.
355
356 UPGRADE
357 =======
358 If you are upgrading from a previous installation of Koha 3, you can
359 use the following:
360
361  perl Makefile.PL --prev-install-log /path/to/koha-install-log
362  make
363  make test
364  sudo make upgrade
365
366 Uninstall Instructions
367 =============================
368 1) Stop Services:
369    $ sudo a2dissite koha
370    $ sudo rm /etc/apache2/sites-available/koha
371    $ sudo apache2ctl restart
372
373    $ sudo update-rc.d koha-zebra-daemon remove
374    $ sudo rm /etc/init.d/koha-zebra-daemon
375
376 2) Remove Database and Indexes
377
378    # MySQL
379    $ mysql -u<kohauser> -p<kohapassword>
380    > drop database koha;
381
382    # Zebra Indexes
383    $ zebraidx -c <prefix>/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
384    $ zebraidx -c <prefix>/etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
385
386 3) Remove Koha Install Directories and Configuration Files
387    Don't forget about any crontab entries
388
389 Tested on the following operating environments
390 ==============================================
391 - Ubuntu Jaunty Jackalope 9.04
392
393 Installer Bug reports
394 =====================
395 Please log any installer bug reports at http://bugs.koha.org
396
397 Other Notes
398 =====================
399 This file is part of Koha
400
401 Koha is free software; you can redistribute it and/or modify it under the
402 terms of the GNU General Public License as published by the Free Software
403 Foundation; either version 2 of the License, or (at your option) any later
404 version.
405
406 Koha is distributed in the hope that it will be useful, but WITHOUT ANY
407 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
408 A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
409 You should have received a copy of the GNU General Public License along
410 with Koha; if not, write to the Free Software Foundation, Inc.,
411 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.