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