View | Details | Raw Unified | Return to bug 7764
Collapse All | Expand All

(-)a/INSTALL.ubuntu (-315 / +666 lines)
Lines 1-448 Link Here
1
=============================
1
=================================================================
2
Installation Guide for Installing Koha on Ubuntu Jaunty (9.04) with MySQL 5
2
Instructions for Installing Koha from Source
3
=============================
3
=================================================================
4
4
5
Copyright (C) 2007, 2008 LibLime (http://liblime.com)
5
INTRODUCTION
6
Some parts copyright 2010 Chris Nighswonger
6
=================================================================
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
7
19
All commands can be performed as a system user with sudo privileges,
8
These are the instructions for installing Koha from source. They
20
as indicated or by running the command directly as root.
9
have been tested using Ubuntu 12.04 LTS. The copyright,
10
licensing, and other details have been put at the end, so the
11
installation can be started as soon as possible.
21
12
22
1. Prepare System and Install Dependencies
13
'nano' is a generic text editor. Please feel free to substitute
14
your favourite editor (vi, emacs, gedit, or etc.).
23
15
24
1.1 Install Ubuntu Jaunty via CD
16
To install Koha for production, it is recommended that you use
17
packages. Installing from packages is not the same as installing
18
from source. These are not your recommended instructions for
19
production servers.
25
20
26
See http://www.ubuntu.com/getubuntu/download
21
To help assist with the development and improvement of Koha,
22
continue with these instructions and read more about version
23
control using git! A link to this cna be found at:
24
http://wiki.koha-community.org/wiki/Version_Control_Using_Git
27
25
28
1.2 Set up your locale
26
These instructions are intended for those who are skilled.
27
They can be used to set up a development system. This install
28
may not be as easy or smooth as you wish. This is to be expected
29
when installing from source.
29
30
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
31
34
http://wiki.koha-community.org/wiki/Encoding_and_Character_Sets_in_Koha
32
NOTATION
33
=================================================================
35
34
36
You can verify your system locale by typing the following command:
35
For the most part, the text surrounded by the plus symbols
36
goes on the command line or an MySQL prompt. However, there
37
will be a "FILE FULL" or "FILE PARTIAL" and the filename above
38
the plus symbols surrounding file contents.
37
39
38
    $ locale
40
Koha is released monthly, so keeping documentation up to date
41
is difficult. The convention is to replace the last number with
42
an x. For example, the current version is part of the 3.14.x
43
series and the former stable version is the 3.12.x series.
44
45
46
INSTALL UBUNTU
47
=================================================================
48
49
These instructions assume that you have already installed Ubuntu
50
from the official site:
51
    - Server edition (command-line only)
52
        http://www.ubuntu.com/download/server
53
54
There is no need to install extra packages during the Ubuntu
55
installation. Apache2 and MySQL will be installed in the
56
instructions later.
57
58
Installing a mail transfer agent before installing Koha will
59
prevent the installation of nullmailer. Such an installation
60
and configuration of a mail transfer agent is beyond the
61
scope of this document. Consult your system administrator,
62
network administrator, or IT Department for assistance as needed.
63
64
These instructions assume you created a user account with your
65
login in credentials and not one called koha. This is to prevent
66
the system user koha from having more permissions than it should.
39
67
40
IMPORTANT:  You _MUST_ follow all the steps outlined there for
41
            Apache2, MySQL 5, etc. BEFORE you install Koha.
42
68
43
1.3 Install the Yaz and Zebra packages
69
ADD A KOHA COMMUNITY REPOSITORY
70
=================================================================
44
71
45
Run the following command to update your system:
72
These instructions still function even though the latest version
73
of Debian is wheezy. If the version has changed again, please
74
confirm these instructions on the mailing list or IRC channel.
46
75
47
    $ sudo apt-get update
76
To avoid getting prompted for a password in the middle of a
48
    $ sudo apt-get install yaz idzebra-2.0 idzebra-2.0-doc
77
chain of commands type the following:
78
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
79
sudo ls
80
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
49
81
50
1.4 Get Koha
82
IF YOU ARE DOING A DEV (typically git) INSTALL use the following
83
command:
84
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
85
echo deb http://debian.koha-community.org/koha squeeze-dev main | sudo tee /etc/apt/sources.list.d/koha.list
86
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
51
87
52
1.4.1 Option A: Download Koha via Git (optional)
88
IF YOU ARE DOING A STANDARD (tarball) INSTALL use the following
89
command:
90
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
91
echo deb http://debian.koha-community.org/koha squeeze main | sudo tee /etc/apt/sources.list.d/koha.list
92
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
53
93
54
    $ sudo apt-get install git-core git-email
94
To use the older stable release:
55
    $ git clone git://git.koha-community.org/koha.git kohaclone
95
echo deb http://debian.koha-community.org/koha oldstable main | sudo tee /etc/apt/sources.list.d/koha.list
56
    $ cd kohaclone
57
    $ git checkout -b myinstall origin
58
96
59
Note: for more information about Git, please see the Koha Git Usage Guide:
97
Add the key in gpg.asc to your APT trusted keys to avoid
98
warning messages on installation.
60
99
61
    http://wiki.koha-community.org/wiki/Version_Control_Using_Git
100
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
101
wget -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -
102
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
62
103
63
1.4.2 Option B: Download Koha from http://download.koha-community.org
64
104
65
    $ wget http://download.koha-community.org/koha-3.00.02.tar.gz
105
UPDATE UBUNTU
66
    ( Note: use the latest stable version)
106
=================================================================
67
107
68
1.5 Install additional Ubuntu dependencies
108
This process, particularly the upgrade step, may take a while.
69
109
70
IMPORTANT:  You should only use CPAN for Perl dependencies which are NOT
110
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
71
            available from the package maintainer. You have been warned!
111
sudo apt-get update
112
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
113
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
114
sudo apt-get upgrade
115
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
116
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
117
sudo apt-get clean
118
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
72
119
73
Using the ubuntu.packages file included in the Koha source tree,
74
run the following:
75
120
76
    $ sudo dpkg --set-selections < install_misc/ubuntu.packages
121
DOWNLOAD THE LATEST KOHA RELEASE
122
=================================================================
77
123
78
Now start dselect (you may need to 'sudo apt-get install dselect'):
124
There are two ways to grab the source, either by using git
125
or by downloading the .tar.gz file. Git is recommended for a
126
development environment.
79
127
80
    $ sudo dselect
128
IF YOU ARE DOING A DEV INSTALLATION:
129
Downloading Source Via Git
130
=================================================================
81
131
82
Choose [I]nstall and accept packages to be installed (hit return)
132
Install the base git installation first:
133
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
134
sudo apt-get install git git-email
135
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
83
136
84
(may take a while)
137
Download Koha (make sure to substitute 'your name' and
138
'your@mail.com' appropriately) and configure git:
139
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
140
git clone git://git.koha-community.org/koha.git kohaclone
141
cd kohaclone
142
git config --global user.name "your name"
143
git config --global user.email "your@mail.com"
144
git config --global core.whitespace trailing-space,space-before-tab
145
git config --global apply.whitespace fix
146
git config --global color.ui auto
147
git checkout -b mywork origin
148
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
85
149
86
Choose [C]onfigure, [R]emove and [Q]uit until dselect has completed.
150
The git clone will download about 620MB (July 2013).
87
151
88
1.6 Install Perl dependencies that aren't packaged into Ubuntu Jaunty
152
IF YOU ARE DOING A STANDARD INSTALLATION:
89
sources
153
Downloading Source Via Tarball
154
=================================================================
90
155
91
Run the following command:
156
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
157
wget http://download.koha-community.org/koha-latest.tar.gz
158
tar xvf koha-latest.tar.gz
159
ls
160
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
92
161
93
    $ sudo cpan GD GD::Barcode::UPCE Algorithm::CheckDigits::M43_001 CHI CHI::Driver::Memcached
162
NOTE: You need to cd into the koha directory, but since the
163
version changes, you'll know by the ls command what it is.
94
164
95
Note: you may need to run CPAN initialization if you've not run cpan
96
before:
97
165
98
    /etc/perl/CPAN/Config.pm initialized.
166
INSTALL DEPENDENCIES
167
=================================================================
99
168
100
    CPAN is the world-wide archive of perl resources. It consists of about
169
Dependencies from Repository
101
    100 sites that all replicate the same contents all around the globe.
170
=================================================================
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
171
106
    If you do not want to enter a dialog now, you can answer 'no' to this
172
The repository added has koha-deps and koha-perldeps packages
107
    question and I'll try to autoconfigure. (Note: you can revisit this
173
which make it very easy. Type the following:
108
    dialog anytime later by typing 'o conf init' at the cpan prompt.)
174
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
175
sudo apt-get install koha-deps koha-perldeps make
176
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
109
177
110
    Are you ready for manual configuration? [yes]
178
Check For Missing Dependencies
179
=================================================================
111
180
112
When the configuration is completed CPAN will install the Perl modules.
181
Check everything was installed, by running the test script to
182
identifty missing libraries:
183
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
184
./koha_perl_deps.pl -m -u
185
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
113
186
114
2. Configuration of dependencies
187
Install any required libraries that are missing. It is a good
188
idea to install optional ones that are easily found as well.
115
189
116
2.1 Update root MySQL password (if dselect didn't do it for you already)
117
190
118
    $ sudo mysqladmin password <password>
191
CREATE MYSQL DATABASE AND GRANT PRIVILEGES
192
=================================================================
119
193
120
2.2 Create the Koha database
194
Create MySQL Database
195
=================================================================
121
196
122
    Create the database and user with associated privileges:
197
If you have difficulty accessing MySQL's root acount, perhaps
198
this Ubuntu page on resetting the root password may help.
199
https://help.ubuntu.com/community/MysqlPasswordReset
123
200
124
    $ mysqladmin -uroot -p<password> create <kohadatabasename>
201
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
125
    $ mysql -uroot -p<password>
202
mysql -u root -p
203
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
126
204
127
    Welcome to the MySQL monitor.  Commands end with ; or \g.
205
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
128
    Your MySQL connection id is 22
206
CREATE DATABASE kohadata;
129
    Server version: 5.0.32-Debian_7etch3-log Debian etch distribution
207
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
130
208
131
    Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
209
The koha database has now been created with the name kohadata.
132
210
133
    mysql> grant all on <kohadatabasename>.* to '<kohadatabaseuser>'@'localhost' identified by '<kohadatabaseuserpassword>';
211
Create User and Grant Permissions
134
    Query OK, 0 rows affected (0.00 sec)
212
=================================================================
135
213
136
    mysql> flush privileges;
214
Continue entering MySQL commands. SUBSTITUTE A PASSWORD OF YOUR CHOICE FOR THE {KOHA USER PASSWORD}'S IN THE FOLLOWING COMMANDS:
137
    Query OK, 0 rows affected (0.00 sec)
138
215
139
    mysql> quit
216
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
217
CREATE user 'koha'@'localhost' IDENTIFIED by '{KOHA USER PASSWORD}';
218
GRANT ALL ON kohadata.* TO 'koha'@'localhost' IDENTIFIED BY '{KOHA USER PASSWORD}';
219
FLUSH PRIVILEGES;
220
QUIT
221
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
140
222
141
2.3 Test your SAX Parser and correct where necessary
223
The koha administrative user has now been created with the name
224
koha and the password of your choosing.
142
225
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
226
145
    $ cd koha
227
CONFIGURE KOHA
146
    $ misc/sax_parser_print.pl
228
=================================================================
147
229
148
    You should see something like::
230
User/Group Environment Variables
231
=================================================================
149
232
150
    XML::LibXML::SAX::Parser=HASH(0x81fe220)
233
IF YOU ARE DOING A DEV INSTALLATION, then create some
234
environment variables for the process to pick up and use later:
235
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
236
export __KOHA_USER__=$USER
237
export __KOHA_GROUP__=$USER
238
echo $USER
239
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
151
240
152
    If you're using PurePerl or Expat, you'll need to edit your
241
The output of the echo command should match your user id,
153
    ini file, typically located at:
242
and since the user id and group id are generally the same for
243
a freshly created account, this will make sure the indexing
244
happens as this account.
154
245
155
    /etc/perl/XML/SAX/ParserDetails.ini
246
IF YOU ARE DOING A STANDARD INSTALLATION, then create a
247
seperate koha system user:
248
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
249
sudo adduser koha
250
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
156
251
157
    You will need to move the entire section for '[XML::LibXML::SAX::Parser]' to the bottom of the ini file.
252
There is no need to set the following environment variables,
253
because koha is the default account to use.
158
254
159
2.4 Install DBD::mysql Perl module
160
255
161
In order to handle UTF-8 correctly, Koha requires at least version 4.004
256
GENERATE MAKE FILE
162
of the DBD::mysql Perl module. However, Debian Etch has a stable package
257
=================================================================
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
258
167
  (1) install without test suite,
259
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
168
  (2) install with test suite requiring a test MySQL DB creation.
260
perl Makefile.PL
261
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
169
262
170
2.4.1 Install without test suite
263
How you answer the first question will affect where things will
264
end up being placed. It is recommended that choose 'standard' if
265
you are doing a tarball install, and 'dev' if you are doing a
266
git install.
171
267
172
Force install DBD::mysql:
268
Answering the resulting questions requires thinking. Here are
269
some hints.
173
270
174
    $ sudo cpan
271
Recall that the database created is kohadata set in the Create
175
    cpan> force install DBD::mysql
272
MySQL Database step. The username and password were set up in
273
the Create User and Grant Permissions step.
176
274
177
2.4.2 Create test database in order to install DBD::mysql
275
Give some thought should be given to the MARC format desired
276
and the method of character normalization (chr or icu), though
277
the defaults will work as MARC21 just fine.
178
278
179
Because of DBD::mysql's test suite, it is necessary to temporarily create a
279
Use the same username and password for the Zebra questions.
180
test database and user:
181
280
182
    $ mysql -uroot -p<password>
281
Don't worry about warnings generated by optional components.
183
282
184
    Create the database and user with associated privileges:
185
283
186
    Welcome to the MySQL monitor.  Commands end with ; or \g.
284
BUILD AND TEST KOHA
187
    Your MySQL connection id is 22
285
=================================================================
188
    Server version: 5.0.32-Debian_7etch3-log Debian etch distribution
189
286
190
    Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
287
Having configured Koha, build it using the following command:
288
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
289
make
290
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
191
291
192
    mysql> create database test;
292
Once this has successfully run, test Koha using the following command:
193
    Query OK, 1 row affected (0.00 sec)
293
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
294
make test
295
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
194
296
195
    mysql> grant all on test.* to 'test'@'localhost' identified by 'test';
297
Don't worry about the large number of scary warning scrolling
196
    Query OK, 0 rows affected (0.00 sec)
298
by. All that matters is "PASS" or "FAIL".
197
    (test database, user, and password can be different if need be)
198
299
199
    mysql> flush privileges;
300
If this fails, it is likely due to a failed dependency. Remember,
200
    Query OK, 0 rows affected (0.00 sec)
301
a source installation is not always smooth. You can determine the
302
missing dependency by scrolling back and looking for something
303
like: Can't locate Cache/Memcached/Fast.pm in @INC
304
Install it, and try to build and test again.
201
305
202
    mysql> quit
203
306
204
Next install DBD::mysql:
307
INSTALL KOHA
308
=================================================================
205
309
206
    $ sudo cpan
310
Once the make test has successfully run, install Koha.
207
311
208
    cpan> o conf makepl_arg
312
IF YOU ARE DOING A DEV INSTALLATION, using the
209
    (get current value of this CPAN parameter)
313
following command (follow any on screen prompts):
314
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
315
make install
316
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
317
No sudo is required as you have access to the directories
318
listed above.
210
319
211
    cpan> o conf makepl_arg "--testdb=test --testuser=test --testpass=test"
320
IF YOU ARE DOING A STANDARD INSTALLATION, using the
321
following command (follow any on screen prompts):
322
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
323
sudo make install
324
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
212
325
213
    cpan> install DBD::mysql
326
Once this has successfully run, Koha is almost installed. There
327
are only a few more steps left.
214
328
215
    cpan> o conf makepl_arg ''
329
At the end of this command the output will have two lines
330
containing KOHA_CONF and PERL5LIB in them. A dev installation
331
may look like:
216
332
217
    OR
333
    Koha's files have now been installed.
218
334
219
    cpan> o conf makepl_arg '<old setting>'
335
    In order to use Koha's command-line batch jobs,
336
    you should set the following environment variables:
220
337
221
    (restore this setting so as to not interfere with future CPAN installs).
338
    export KOHA_CONF=/home/{your user name}/koha-dev/etc/koha-conf.xml
339
    export PERL5LIB=/home/{your user name}/kohaclone
222
340
341
    For other post-installation tasks, please consult the README.
223
342
224
Finally, remove the test database:
343
Take note of the two export commands as you will need them
344
for a later step.
225
345
226
    $ mysql -uroot -p<password>
227
346
228
    mysql> drop database test;
347
PRE-WEB INSTALL SETUP
229
    Query OK, 1 row affected (0.00 sec)
348
=================================================================
230
349
231
    mysql> exit
350
UBUNTU MYSQL SECURITY TWEAK
232
    Bye
351
=================================================================
233
352
234
3. Run the Koha installer
353
There is a security risk in Ubuntu's MySQL default set up. Type
354
the following commands:
355
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
356
mysql -u root -p
357
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
235
358
236
    $ perl Makefile.PL
359
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
237
    ( answer questions )
360
USE mysql;
238
    $ make
361
DELETE FROM user WHERE user='';
239
    $ make test
362
FLUSH PRIVILEGES;
240
    $ sudo make install
363
QUIT
364
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
241
365
242
4. Configure and start Apache
366
The anonymous connections are now removed.
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
367
247
Add the following lines to /etc/apache2/ports.conf:
248
368
249
    Listen 80
369
CONFIGURE SYSTEM WIDE ENVIRONMENT VARIABLES
250
    Listen 8080
370
=================================================================
251
371
252
If not running named virtual hosts (The default koha installation does not use named virtual hosts.), comment out the following line:
372
Running scripts and cron jobs requires environment variables set.
373
Use the following commands:
374
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
375
sudo nano /etc/environment
376
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
253
377
254
    NameVirtualHost *:80
255
378
256
Run the following commands:
379
IF YOU ARE DOING A DEV INSTALLATON:
380
FILE PARTIAL (ADD): /etc/environment
381
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
382
KOHA_CONF=/home/{YOUR USER NAME}/koha-dev/etc/koha-conf.xml
383
KOHA_PATH=/home/{YOUR USER NAME}/kohaclone
384
PERL5LIB=/home/{YOUR USER NAME}/kohaclone
385
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
386
NOTE: CHANGE {YOUR USER NAME} TO YOUR ACTUAL USER NAME!
387
388
IF YOU ARE DOING A STANDARD INSTALLATON:
389
FILE PARTIAL (ADD): /etc/environment
390
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
391
KOHA_CONF=/etc/koha/koha-conf.xml
392
KOHA_PATH=/usr/share/koha
393
PERL5LIB=/usr/share/koha/lib
394
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
395
396
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
397
logout
398
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
399
You need to logout and back in in order to get the environment
400
variables values to be recognized.
401
402
403
CONFIGURE AND START APACHE
404
=================================================================
405
406
Place Koha Site File
407
=================================================================
408
409
IF YOU ARE DOING A DEV INSTALLATION, use the following command:
410
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
411
sudo ln -s ~/koha-dev/etc/koha-httpd.conf /etc/apache2/sites-available/koha
412
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
413
414
IF YOU ARE DOING A STANDARD INSTALLATION, use the following command:
415
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
416
sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha
417
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
418
419
Tweak Koha Site File
420
=================================================================
421
422
The default file limits connections to those from 127.0.1.1
423
(or 127.0.0.1), which is rather difficult to test/use in a
424
server environment. Edit the file:
425
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
426
sudo nano /etc/apache2/sites-available/koha
427
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
428
429
/etc/apache2/sites-available/koha will have a line
430
that should have the IP address changed to a *.
431
FILE PARTIAL (CHANGE): /etc/apache2/sites-available/koha
432
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
433
<VirtualHost *:80>
434
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
435
436
/etc/apache2/sites-available/koha will have another line
437
that should have the IP address changed to a *
438
FILE PARTIAL (CHANGE): /etc/apache2/sites-available/koha
439
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
440
<VirtualHost *:8080>
441
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
442
443
Setup Default Ports
444
=================================================================
445
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
446
sudo nano /etc/apache2/ports.conf
447
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
448
449
/etc/apache2/ports.conf must have two lines exactly like
450
the following.  Do not add them if they are already there.
451
452
FILE PARTIAL (CONFIRM/ADD/CHANGE): /etc/apache2/ports.conf
453
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
454
Listen 80
455
Listen 8080
456
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
457
458
/etc/apache2/ports.conf does not require NameVirtualHost.
459
Do not add it if it is missing or already there. Just
460
prepend # accordingly.
461
462
FILE PARTIAL (CONFIRM/ADD/CHANGE): /etc/apache2/ports.conf
463
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
464
#NameVirtualHost *:80
465
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
466
467
Disable Default Site
468
=================================================================
469
470
These short instructions assume that the default site is
471
not needed.  Talk with your system administrator, network
472
administrator, or IT Department to CONFIRM THIS BEFORE RUNNING
473
the following command:
474
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
475
sudo a2dissite 000-default
476
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
477
478
Enable Modules and Site
479
=================================================================
480
481
Now enable the apache modules this config needs, enable koha's
482
configuration, and restart apache.
483
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
484
sudo a2enmod rewrite
485
sudo a2enmod deflate
486
sudo a2ensite koha
487
sudo service apache2 restart
488
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
489
490
491
SETUP ZEBRA
492
=================================================================
493
494
The zebra process send responses to search requests sent by Koha
495
or Z39.50/SRU/SRW clients.
496
497
The user you run Zebra as will be the only user with write
498
permission on the Zebra index. For a standard installation, this
499
should be the system user 'koha'. For a dev installation, this
500
should be your system user.
501
502
Start Zebra Server on Boot
503
=================================================================
504
505
IF YOU ARE DOING A DEV INSTALLATION, use this command:
506
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
507
sudo ln -s ~/koha-dev/bin/koha-zebra-ctl.sh /etc/init.d/koha-zebra-daemon
508
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
509
510
IF YOU ARE DOING A STANDARD INSTALLATION, use this command:
511
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
512
sudo ln -s /usr/share/koha/bin/koha-zebra-ctl.sh /etc/init.d/koha-zebra-daemon
513
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
514
515
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
516
sudo update-rc.d koha-zebra-daemon defaults
517
sudo service koha-zebra-daemon start
518
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
519
520
Configuring Zebra Indexing
521
=================================================================
522
523
IF YOU ARE DOING A DEV INSTALLATION, use this command:
524
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
525
crontab -e
526
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
257
527
258
    $ sudo a2enmod rewrite deflate
528
FILE PARTIAL (ADD):
259
    $ sudo a2ensite koha
529
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
260
    $ sudo apache2ctl restart
530
# The cronjobs -- $KOHA_PATH is defined in /etc/environment, and gets set when this process runs.
531
*/5 * * * *	$KOHA_PATH/misc/migration_tools/rebuild_zebra.pl -b -a -z &> /dev/null
532
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
261
533
262
Note: you may still see the usual Apache default site if your VirtualHost
534
IF YOU ARE DOING A STANDARD INSTALLATION, use this command:
263
configuration isn't correct.  The command "sudo a2dissite default" may be a
535
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
264
quick fix, but may have side-effects.  See the Apache HTTPD manual section on
536
sudo nano /etc/cron.d/koha
265
virtual hosts for full instructions.
537
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
266
538
267
5. Configure and start Zebra
539
FILE FULL: /etc/cron.d/koha
540
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
541
# The cronjobs -- $KOHA_PATH is defined in /etc/environment, and gets set when this process runs as a user (koha).
542
*/5 * * * * koha $KOHA_PATH/bin/migration_tools/rebuild_zebra.pl -b -a -z &> /dev/null
543
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
268
544
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
545
274
Note: it's also recommended that you create a Koha system user, which you will
546
SETUP ADDITIONAL LANGUAGES
275
have specified during the install process. Alternatively, Zebra can be
547
=================================================================
276
configured to run as the root user.
277
548
278
To add a user do:
549
To use multi-lingual sample data, please install languages
550
which may be useful for use in the Koha system.
279
551
280
    $ sudo adduser koha
552
Information on this can be found:
553
http://wiki.koha-community.org/wiki/Installation_of_additional_languages_for_OPAC_and_INTRANET_staff_client
281
554
282
Option 1: run the Zebra processes from the command line:
283
555
284
5.1.1 Zebra Search Server
556
WEB INSTALLATION
557
=================================================================
285
558
286
This process send responses to search requests sent by Koha or
559
Now you can visit your staff client website to continue with the
287
Z39.50/SRU/SRW clients.
560
Koha web installer. The user name to log in with will be koha.
288
561
289
    $ sudo -u ${KOHA_USER} zebrasrv -f /etc/koha/koha-conf.xml
562
The password will be what you set in the 'Create User and
290
    (note that the path to koha-conf.xml may be different depending on your
563
Grant Permissions' section above.
291
    installation choices)
292
564
293
Note: the user you run Zebra as will be the only user with write permission
565
Lynx navigational keys include: tab to go between fields, enter
294
      on the Zebra index; in development mode, you may wish to use your
566
(when not on text fields) to toggle or click, space to change
295
      system user.
567
pages (when not on text fields), Q to quit (when not on text
568
fields). Arrows also work.
296
569
297
5.1.2 Zebra Indexer
570
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
571
sudo apt-get install lynx
572
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
573
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
574
lynx http://127.0.1.1:8080/
575
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
298
576
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
577
303
    $ sudo -u ${KOHA_USER} misc/migration_tools/rebuild_zebra -z -b -a
578
SETUP YOUR LIBRARY IN KOHA
304
    NOTE: This script should be run as the kohauser (the default is 'koha').
579
=================================================================
305
580
306
Option 2: run the Zebra process as a daemon, and add to startup process:
581
After the web install, you should be redirected to:
582
http://127.0.1.1:8080
583
Follow these steps:
584
- Login with koha user name and password.
585
- Click on the More dropdown menu.
586
- Select and click Administration.
587
- Click Libraries and groups
588
  under the Basic Parameters heading.
589
- Click New Library and enter your information into the form.
590
- Click Submit.
591
Your Library is now setup in Koha.
307
592
308
Note that references to $SCRIPT_DIR refer to the directory where
593
Take the time to read the documentation to do other necessary
309
Koha's command-line scripts are installed, e.g., /usr/share/koha/bin.
594
setup tasks such as creating a patron, and importing or entering
595
MARC data. The documentation for Koha can be found at:
596
http://koha-community.org/documentation/
310
597
311
5.2.1 Zebra Search Server
312
598
313
    $ sudo ln -s ${SCRIPT_DIR}/koha-zebra-ctl.sh  /etc/init.d/koha-zebra-daemon
599
USEFUL REFERENCE LINKS
314
    (Note: ${SCRIPT_DIR} is /usr/share/koha/bin/ by default in a standard install)
600
=================================================================
315
    $ sudo update-rc.d koha-zebra-daemon defaults
316
    ( Note: see man chkconfig(8) on other distros )
317
601
318
    $ sudo ${SCRIPT_DIR}/koha-zebra-ctl.sh start
602
Documentation:
603
http://koha-community.org/documentation/
319
604
320
5.2.2 Zebra Indexer
605
Additional Languages:
606
http://wiki.koha-community.org/wiki/Installation_of_additional_languages_for_OPAC_and_INTRANET_staff_client
321
607
322
Add an entry in Koha user crontab to scheduled added/updated/deleted records
608
Stage MARC Records for Import:
323
indexing by Zebra with this command:
609
http://manual.koha-community.org/3.14/en/catalogtools.html#stagemarc
610
NOTE: The URL has been similar since Koha version 3.8
324
611
325
  <path/to/koha>/misc/migration_tools/rebuild_zebra -z -b -a
612
Frequently Asked Questions:
613
http://koha-community.org/documentation/faq
326
614
327
See check misc/cronjobs/crontab.example for usage examples.
615
Bug Reports:
328
NOTE: This job should be setup under the kohauser (the default is 'koha').
616
http://bugs.koha-community.org/
329
617
330
You can also configure zebra-indexing as an background daemon, see http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra
618
Public Z39.50/SRU server:
619
http://wiki.koha-community.org/wiki/Troubleshooting_Koha_as_a_Z39.50_server
331
620
332
6. Run the Web Installer, populate the database, initial configuration of settings
333
621
334
    Point your browser to http://<servername>:8080/
622
UPGRADE
335
623
=================================================================
336
    It should redirect you to the Web Installer where you can continue the setup.
624
337
    You can install the sample data for libraries, patrons, etc. via the Web Installer
625
If you are running in another language other than English,
338
626
please switch to English before doing the upgrade, the
339
7. What next?
627
templating system has changed and the templates will need to
628
be regenerated.
629
630
Once you have upgraded, please regenerate your templates in
631
your chosen languages.
632
633
First, ensure the most recent dependencies are installed:
634
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
635
sudo apt-get update
636
sudo apt-get install koha-deps koha-perldeps
637
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
638
639
640
IF YOU ARE DOING A DEV UPGRADE:
641
In order to upgrade, find the path to the koha install-log file:
642
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
643
sudo find ~/koha-dev/ -name 'koha-install-log'
644
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
645
646
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
647
cd ~/kohaclone
648
perl Makefile.PL --prev-install-log /path/to/koha-install-log
649
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
650
NOTE: Make sure to change the /path/to/koha-install-log to the
651
one that was found.
652
653
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
654
make
655
make test
656
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
657
658
And if that passes:
659
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
660
make upgrade
661
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
662
663
IF YOU ARE DOING A STANDARD UPGRADE:
664
In order to upgrade, find the path to the koha install-log file:
665
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
666
sudo find /usr/share/koha/ -name 'koha-install-log'
667
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
668
669
Change directory into the latest koha source directory, and then:
670
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
671
perl Makefile.PL --prev-install-log /path/to/koha-install-log
672
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
673
NOTE: Make sure to change the /path/to/koha-install-log to the
674
one that was found.
675
676
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
677
make
678
make test
679
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
680
681
And if that passes:
682
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
683
sudo make upgrade
684
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
685
686
687
REGARDLESS OF UPGRADE TYPE:
688
If you are upgrading from a version of Koha earlier than 3.4.x,
689
Koha 3.4.x or later no longer stores items in biblio records.
690
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
691
./misc/maintenance/remove_items_from_biblioitems.pl --run
692
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
693
694
Regardless of version you are upgrading from, a full reindex is
695
always the best option:
696
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
697
./misc/migration_tools/rebuild_zebra.pl -b -a -r -v
698
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
699
700
701
UNINSTALL INSTRUCTIONS
702
=================================================================
703
704
Stop Services
705
=================================================================
706
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
707
sudo a2dissite koha
708
sudo rm /etc/apache2/sites-available/koha
709
sudo service apache2 restart
710
sudo update-rc.d koha-zebra-daemon remove
711
sudo rm /etc/init.d/koha-zebra-daemon
712
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
713
714
Remove Database
715
=================================================================
716
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
717
mysql -u koha -p
718
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
719
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
720
drop database kohadata;
721
quit
722
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
723
724
Remove Indexes
725
=================================================================
726
727
IF DOING A DEV REMOVAL:
728
The following will work, but is very dangerous! Please copy or
729
type this correctly.
730
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
731
zebraidx -c ~/koha-dev/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
732
zebraidx -c ~/koha-dev/etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
733
rm -rf ~/koha-dev
734
rm -rf ~/kohaclone
735
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
736
NOTE: Don't forget to remove the crontab entries!
737
738
IF DOING A STANDARD REMOVAL:
739
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
740
zebraidx -c /etc/koha/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
741
zebraidx -c /etc/koha/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
742
sudo rm -rf /etc/koha
743
sudo rm -rf /usr/share/koha
744
sudo rm /etc/cron.d/koha
745
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
746
747
You may wish to follow up with:
748
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
749
sudo find / -t d -name "koha"
750
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
751
to help find any remnants.
752
753
754
COPYRIGHTS AND INFORMATION
755
=================================================================
756
This document last modified: 01 September 2013
757
758
Major re-write by Mark Tompsett
759
Copyright (C) 2013
760
761
Based on remnants by:
762
Copyright (C) 2007, 2008 LibLime (http://liblime.com)
763
                          Original author: Joshua Ferraro
764
Some parts copyright 2010 Chris Nighswonger (modified for ubuntu)
765
                          (cnighswonger AT foundations DOT edu)
766
Some parts copyright 2012 Tomas Cohen Arazi
767
                          (tomascohen AT gmail DOT com)
768
Some parts copyright 2012 Mark Tompsett
769
                          (mtompset AT hotmail DOT com)
340
770
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
771
345
    $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml
772
BUG REPORTS AND FEEDBACK
346
      (note: use the correct path to your koha-conf.xml)
773
=================================================================
774
Given the nature of documentation to become outdated, or have
775
problems, please either submit feedback or bug reports.
347
776
348
7.1 Import:
777
Bug reports can be posted at http://bugs.koha-community.org
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
778
354
7.2 Fast Index:
779
Feedback can be posted on the Koha Developer's List:
355
    $ misc/migration_tools/rebuild_zebra.pl -b -w
780
http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
356
781
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
782
360
7.3 Schedule regular index updates
783
LICENSE
784
=================================================================
361
785
362
    You need to run rebuild_zebra.pl -b -a -z as a regular cron job in orde to pick up new bibs
786
This file is part of Koha.
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
787
366
    You can also indexing in background, see 5.2.2 above
788
Koha is free software; you can redistribute it and/or modify it
789
under the terms of the GNU General Public License as published by
790
the Free Software Foundation; either version 3 of the License, or
791
(at your option) any later version.
367
792
368
7.4 To enable public Z39.50/SRU servers, you'll need to edit your koha-conf.xml and
793
Koha is distributed in the hope that it will be useful, but
369
    change the <listen> options to listen on a TCP port; then restart the zebra daemon.
794
WITHOUT ANY WARRANTY; without even the implied warranty of
795
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
796
GNU General Public License for more details.
370
797
371
UPGRADE
798
You should have received a copy of the GNU General Public License
372
=======
799
along with Koha; if not, see <http://www.gnu.org/licenses>.
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.
(-)a/INSTALL.ubuntu.12.04 (-571 lines)
Lines 1-571 Link Here
1
=================================================================
2
Installation Guide for Installing Koha
3
on Ubuntu Precise Pangolin (12.04 LTS) with MySQL 5.5
4
=================================================================
5
6
Copyright (C) 2007, 2008 LibLime (http://liblime.com)
7
Some parts copyright 2010 Chris Nighswonger
8
Some parts copyright 2012 Tomas Cohen Arazi
9
Some parts copyright 2012 Mark Tompsett
10
11
Original author: Joshua Ferraro
12
Modified for Ubuntu by: Chris Nighswonger
13
                        (cnighswonger AT foundations DOT edu)
14
15
More updates by: Tomas Cohen Arazi (tomascohen AT gmail DOT com)
16
                 Mark Tompsett (mtompset AT hotmail DOT com)
17
18
Feedback/bug reports: Koha Developer's List:
19
http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
20
21
This document last modified: 24 July 2012
22
23
Installation Instructions
24
=================================================================
25
26
Running commands can mostly be performed as a system user with
27
sudo privileges, however some need to be run directly as root.
28
29
1. Prepare System and Install Dependencies
30
31
1.1 Install Ubuntu 12.04 LTS via CD/DVD/USB
32
33
  Download and install Ubuntu from the official site.
34
    - Server edition (command-line only)
35
        http://www.ubuntu.com/download/server
36
    - Desktop edition
37
        http://www.ubuntu.com/download/desktop
38
  To keep your Koha installation minimal and to free resources
39
  for running, the Server edition is recommended, though the
40
  Desktop edition will work as well.
41
42
  As Apache and MySQL will be installed in the instructions
43
  later, there is no need to select any packages during the
44
  installation of Ubuntu.
45
46
1.2 Add koha repository to your apt sources
47
48
  NOTE: This is not required for koha 3.6.7 under Ubuntu 12.04
49
        if Zebra indexing (see step 5.2) is done via cron jobs.
50
  NOTE: 3.8.x is the recommended current stable release to use.
51
52
  There are currently three active repositories: oldstable,
53
  squeeze, and squeeze-dev. As of 2012-07-24, they represent
54
  3.6.x, 3.8.x, and master respectively. This will change when
55
  3.10.x is released. They will represent 3.8.x, 3.10.x, and
56
  master respectively.
57
58
  It is recommended to use squeeze at this time, as 3.8.x is the
59
  current stable release.
60
61
  Run these commands:
62
    $ echo "deb http://debian.koha-community.org/koha squeeze main" | sudo tee /etc/apt/sources.list.d/koha-community.list
63
    $ wget -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -
64
    $ sudo apt-get update ; sudo apt-get upgrade
65
66
1.3 Install Apache2 and MySQL 5.5
67
68
  Install the Apache2 server:
69
    $ sudo apt-get install apache2
70
71
  If your MySQL server will be on your Koha server, or this
72
  instruction is confusing:
73
    $ sudo apt-get install mysql-server
74
75
  NOTE: You will be prompted to set your root password for MySQL.
76
77
1.4 Set up your locale
78
79
  Your locale should be set to UTF-8, as should Apache2 and
80
  MySQL 5.5. This step is VERY IMPORTANT for a UNICODE compliant
81
  system. You _MUST_ be sure to set this BEFORE you install Koha.
82
83
1.4.1 Ubuntu Locale
84
85
  Verify you have a UTF-8 locale in use:
86
    $ locale
87
  You will recognize if it is UTF-8 or not. Ubuntu 12.04 should
88
  not generally require any further steps.
89
90
  If it is not set to something UTF-8, use:
91
    $ locale -a
92
93
  You can select one (note that utf8 becomes UTF-8) and use:
94
    $ sudo update-locale LANG=en_US.UTF-8
95
96
  You have to log out and back in to see locale change reflected
97
  in the locale command.
98
99
  Verify your system local by running the following command:
100
    $ locale
101
102
1.4.2 Apache2 and MySQL Locales
103
  Please read over the following document carefully for more
104
  information:
105
    http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Configuring_the_Character_Set
106
107
1.5 Get Koha
108
109
  There are two ways to install Koha. The easy way is using Debian/Ubuntu
110
  packages (check http://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages
111
  for further instructions).
112
113
  The other way is installing from sources. You can get Koha's source
114
  either using git (see 1.5.1) or downloading the stable release tarball.
115
116
  1.5.1 Download from Git
117
118
  Install Git:
119
    $ sudo apt-get install git
120
121
  Download Koha (the 3.10.x branch):
122
    $ git clone git://git.koha-community.org/koha.git kohaclone
123
    $ cd kohaclone
124
    $ git checkout -b myinstall origin/3.10.x
125
126
  NOTE: for more information about Git, please see the Koha Git
127
        Usage Guide:
128
   http://wiki.koha-community.org/wiki/Version_Control_Using_Git
129
130
  1.5.2 Download from Tarball
131
132
  You can get the sources from
133
   http://download.koha-community.org. Issuing the following
134
  command you can get the latest stable release (recommended):
135
136
  Download and Unpack Koha:
137
    $ wget http://download.koha-community.org/koha-latest.tar.gz
138
    $ tar xvf koha-latest.tar.gz
139
140
  Determine the version and change directory:
141
    $ ls
142
    koha-3.10.00  koha-latest.tar.gz
143
    $ cd koha-3.10.00
144
145
146
1.6 Install additional Ubuntu dependencies
147
148
  Several Koha dependencies have been conveniently packaged and
149
  will be installed issuing the following command:
150
151
    $ sudo apt-get install `cat install_misc/ubuntu.12.04.packages | \
152
            cut -f1 | grep -v '#' | grep -v -e '^$'`
153
154
  Confirm that you want to install the required packages when prompted,
155
156
1.7 Install Perl dependencies that aren't packaged
157
158
****************************************************************
159
  IMPORTANT:  You should only use CPAN for Perl dependencies
160
              which are NOT available from the package
161
              maintainer. You have been warned!
162
****************************************************************
163
164
  Run the test script to identify missing libraries
165
    $ ./koha_perl_deps.pl -m -u
166
167
  If there are any dependencies which are missing or need
168
  upgrading, first attempt aptitude searches:
169
    $ aptitude search libbusiness-isdn-perl
170
171
  Notice how the name transformed to 'lib' plus the lowercase
172
  library name using '-'s instead of '::'s plus '-perl'. This
173
  will generally help find what is missing. And then a simple
174
  apt-get install can be done:
175
    $ sudo apt-get install libbusiness-isdn-perl
176
177
  Do this for all the dependencies listed. Then re-run the
178
  command:
179
    $ ./koha_perl_deps.pl -m -u
180
181
  In general, the repositories on debian.koha-community.org
182
  should have any missing pieces. The list should be empty.
183
184
  If any are still listed, they can be installed using the 'cpan'
185
  command. If and only if you are unable to find any of the
186
  dependencies should you use the cpan command. For example:
187
    $ sudo cpan GD GD::Barcode::UPCE Algorithm::CheckDigits
188
189
  NOTE: you may need to run CPAN initialization if you've not run
190
        cpan before:
191
--------
192
    /etc/perl/CPAN/Config.pm initialized.
193
194
    CPAN is the world-wide archive of perl resources. It consists of about
195
    100 sites that all replicate the same contents all around the globe.
196
    Many countries have at least one CPAN site already. The resources
197
    found on CPAN are easily accessible with the CPAN.pm module. If you
198
    want to use CPAN.pm, you have to configure it properly.
199
200
    If you do not want to enter a dialog now, you can answer 'no' to this
201
    question and I'll try to autoconfigure. (Note: you can revisit this
202
    dialog anytime later by typing 'o conf init' at the cpan prompt.)
203
204
    Are you ready for manual configuration? [yes]
205
--------
206
  When the configuration is completed CPAN will install the Perl
207
  modules passed on the command-line.
208
209
  For further explanation and reading see:
210
     http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Ubuntu_Packages_for_Perl_Dependencies
211
212
213
2. Configuration of dependencies
214
215
2.1 Update root MySQL password
216
217
  If during the installation of MySQL you were not prompted to
218
  set the MySQL password:
219
    $ sudo mysqladmin password <password>
220
221
2.2 Create the Koha database
222
223
  Create the database and user with associated privileges. To do
224
  this, decide on the koha database name, the koha user name, and
225
  the koha user password. Substitute these into the following
226
  commands:
227
    $ mysql -u root -p
228
    Enter mysql root password:
229
    Welcome to the MySQL monitor.  Commands end with ; or \g.
230
    Your MySQL connection id is 42
231
    Server version: 5.5.24-0ubuntu0.12.04.1 (Ubuntu)
232
233
    Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.
234
235
    Oracle is a registered trademark of Oracle Corporation and/or its
236
    affiliates. Other names may be trademarks of their respective
237
    owners.
238
239
    Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
240
241
    mysql> CREATE DATABASE {kohadatabasename};
242
    mysql> SHOW DATABASES;
243
    mysql> CREATE user '{kohauserbasename}'@'localhost' IDENTIFIED by '{kohauserpassword}';
244
    mysql> GRANT ALL ON {kohadatabasename}.* TO '{kohausername}'@'localhost' IDENTIFIED BY '{kohauserpassword}';
245
    mysql> USE mysql;
246
    mysql> SELECT host,user FROM user;
247
    mysql> DELETE FROM user WHERE user='';
248
    mysql> SELECT host,user FROM user;
249
    mysql> FLUSH PRIVILEGES;
250
    mysql> QUIT
251
252
  For further explanation of these commands see:
253
    http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Create_MySQL_Database_and_Grant_Privileges
254
255
256
2.3 Test your SAX Parser and correct where necessary
257
258
  You must be sure you're using the XML::LibXML SAX parser, not
259
  Expat or PurePerl, both of which have outstanding bugs with
260
  pre-composed characters. Test your SAX parser by running:
261
    $ ./misc/sax_parser_print.pl
262
263
  If your setup is wrong, the script will output something like:
264
    Koha wants something like:
265
      XML::LibXML::SAX::Parser=HASH(0x81fe220)
266
    You have:
267
      XML::SAX::Expat=HASH(0x1a94e88)
268
    Looks bad, check INSTALL.* documentation.
269
270
  It means you are using Expat (it could also say PurePerl).
271
  You'll need to edit your ini file, located at:
272
    /etc/perl/XML/SAX/ParserDetails.ini
273
274
  Move the entire section for '[XML::LibXML::SAX::Parser]' to the
275
  bottom of the ini file. Then run the script again. The output
276
  should look like this:
277
    $ misc/sax_parser_print.pl
278
    Koha wants something like:
279
      XML::LibXML::SAX::Parser=HASH(0x81fe220)
280
    You have:
281
      XML::LibXML::SAX::Parser=HASH(0x16dfee8)
282
    Looks good.
283
284
  For further details see:
285
    http://wiki.koha-community.org/wiki/Koha_on_Ubuntu#Test_to_make_sure_the_SAX_Parser_is_setup_correctly
286
287
288
3. Run the Koha installer
289
290
  Add a user for installing koha and running zebra:
291
    $ sudo adduser koha
292
293
  Build and install Koha:
294
    $ perl Makefile.PL
295
    ( answer questions )
296
    $ make
297
    $ make test
298
    $ sudo make install
299
300
301
4. Configure and start Apache
302
303
  This will help make koha available to be a website:
304
   $ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha
305
306
  NOTE: the path to koha-httpd.conf may be different depending on
307
        your installation choices.
308
309
  Make sure you have this lines in /etc/apache2/ports.conf:
310
    Listen 80
311
    Listen 8080
312
  Add the missing one.
313
314
  The default installation of Koha does not use named virtual
315
  hosts. If you will not be running named virtual hosts, comment
316
  out the following line:
317
    NameVirtualHost *:80
318
319
  Run the following commands:
320
    $ sudo a2enmod rewrite deflate
321
    $ sudo a2ensite koha
322
    $ sudo apache2ctl restart
323
324
  Note: you may still see the usual Apache default site if your
325
        VirtualHost configuration isn't correct.  The command
326
        "sudo a2dissite default" may be a quick fix, but may have
327
        side-effects.  See the Apache HTTPD manual section on
328
        virtual hosts for full instructions.
329
330
331
5. Configure and start Zebra
332
333
  This process send responses to search requests sent by Koha or
334
  Z39.50/SRU/SRW clients.
335
336
  NOTE: the user you run Zebra as will be the only user with
337
        write permission on the Zebra index; in development mode,
338
        you may wish to use your system user.
339
340
341
5.1 Zebra Search Server
342
343
  Set the zebra daemon to run on start:
344
    $ sudo ln -s /usr/share/koha/bin/koha-zebra-ctl.sh /etc/init.d/koha-zebra-daemon
345
    $ sudo update-rc.d koha-zebra-daemon defaults
346
    $ sudo /etc/init.d/koha-zebra-daemon start
347
348
  NOTE: change the path to koha-zebra-ctl.sh to match your setup
349
        if not using the default.
350
351
352
5.2 Zebra Indexer
353
354
  There are two ways to do this. ONLY DO ONE! DO NOT DO BOTH!
355
356
  Option 1:
357
    You can configure zebra-indexing as an background daemon, see
358
      http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra
359
360
  Option 2:
361
362
    Add an entry in Koha user crontab to scheduled
363
    added/updated/deleted records indexing by Zebra with this
364
    command:
365
      <path/to/koha>/misc/migration_tools/rebuild_zebra -z -b -a
366
367
    See check misc/cronjobs/crontab.example for usage examples.
368
369
    NOTE: This job should be setup under the kohauser
370
          (the default is 'koha').
371
372
373
6. Run the Web Installer, populate the database,
374
   initial configuration of settings
375
376
  The hope is that your server is accessible via a nice browser
377
  somewhere. If not, install lynx to finish the web install on
378
  your Koha server:
379
    $ sudo apt-get install lynx
380
381
  Point your browser to http://<servername>:8080/
382
383
  If you installed lynx, and are using defaults, it might be
384
  something like:
385
    $ lynx http://127.0.1.1:8080/
386
387
  It should redirect you to the Web Installer where you can
388
  continue the setup. You can install the sample data for
389
  libraries, patrons, etc. via the Web Installer
390
391
392
7. Install additional languages
393
394
  In your install directory you can run this commands to have
395
  your Koha setup translated to your language:
396
397
  Set your environment variables:
398
    $ export KOHA_CONF=/etc/koha/sites/koha/koha-conf.xml
399
    $ export PERL5LIB=/usr/share/koha/lib/
400
401
  NOTE: the path to koha-conf.xml may be different depending on
402
        your installation choices.
403
404
  Run the translator script:
405
    $ cd /usr/share/koha/misc/translator
406
    $ perl translate install <language-code>
407
408
  <language-code> must be one of the included in the
409
  misc/translator/po directory.
410
411
  NOTE: You can add as many languages as you need. In order to
412
        use them you will have to enable them first in the
413
        'I18N/L10N' section of the Koha preferences.
414
415
416
8. What next?
417
418
  NOTE: You can use the 'Stage MARC records for import' from the
419
        Tools area of Koha's Staff Client to import a batch of
420
        MARC records, rather than these instructions.
421
422
  Once the installer has completed, you can import and index MARC
423
  records from the command line thusly:
424
    $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml
425
  NOTE: use the correct path to your koha-conf.xml
426
427
8.1 Import
428
429
  Bibliographic data in MARC21 format:
430
    $ misc/migration_tools/bulkmarcimport.pl -file /path/to/marc.iso2709
431
432
  Authority data in MARC21 format:
433
    $ misc/migration_tools/bulkauthimport.pl -file /path/to/auth.iso2709
434
435
8.2 Fast Index:
436
437
  NOTE: This script must be run as the kohauser otherwise
438
        permission errors and indexing problems will follow.
439
        (the default is 'koha' -- see step 3).
440
441
    $ misc/migration_tools/rebuild_zebra.pl -b -w
442
443
  Once the indexing has completed, you will be able to search for
444
  records in your system.
445
446
447
8.3 Public Z39.50/SRU server
448
449
  To enable public Z39.50/SRU servers, you'll need to edit your
450
  koha-conf.xml and change the <listen> options to listen on a
451
  TCP port; then restart the zebra daemon.
452
453
454
UPGRADE
455
=================================================================
456
457
  If you are running in another language other than English,
458
  please switch to English before doing the upgrade, the
459
  templating system has changed and the templates will need to be
460
  regenerated.
461
462
  Once you have upgraded, please regenerate your templates in
463
  your chosen languages.
464
465
466
1. Install new Perl dependencies
467
468
  If you are upgrading from a previous installation of Koha 3.x,
469
  you can use the following to identify new Perl dependencies:
470
    $ ./koha_perl_deps.pl -u -m
471
472
  Install any missing modules using the instructions on sections
473
  1.6 and 1.7.
474
475
476
2. Upgrade Koha
477
478
    $ perl Makefile.PL --prev-install-log /path/to/koha-install-log
479
    $ make
480
    $ make test
481
    $ sudo make upgrade
482
483
484
3. Pre-3.4 upgrades
485
486
  Koha 3.4.x or later no longer stores items in biblio records so
487
  if you are upgrading from an older version as part of the
488
  upgrade you will need to do the following two steps, they can
489
  take a long time (several hours) to complete for large
490
  databases:
491
    $ misc/maintenance/remove_items_from_biblioitems.pl --run
492
    $ misc/migration_tools/rebuild_zebra.pl -b -r
493
494
495
Uninstall Instructions
496
=================================================================
497
498
1. Stop Services:
499
500
  Firstly, remove the apache website:
501
    $ sudo a2dissite koha
502
    $ sudo rm /etc/apache2/sites-available/koha
503
    $ sudo apache2ctl restart
504
505
  Next, remove the koha-zebra-daemon:
506
    $ sudo update-rc.d koha-zebra-daemon remove
507
    $ sudo rm /etc/init.d/koha-zebra-daemon
508
509
510
2a. Remove Database:
511
512
  Remember the <kohauser>, <kohapassword, and <kohadatabasename>
513
  need to be substituted on the following commands:
514
   $ mysql -u<kohauser> -p<kohapassword>
515
   mysql> drop database <kohadatabasename>;
516
517
518
2b. Remove Indexes:
519
520
  To help determine what <prefix> should be substituted with,
521
  run the following command:
522
    $ sudo find / -name "zebra-biblios.cfg"
523
    /etc/koha/zebradb/zebra-biblios.cfg
524
    /home/user/koha-3.08.03/etc/zebradb/zebra-biblios.cfg
525
    /home/user/koha-3.08.03/blib/ZEBRA_CONF_DIR/zebra-biblios.cfg
526
  There may be three copies, two of which will likely be in the
527
  user account that installed Koha. In this example, our <prefix>
528
  is '/etc/koha'.
529
530
  Once you know the value of prefix, run these commands
531
  substituting in the correct value:
532
   $ zebraidx -c <prefix>/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
533
   $ zebraidx -c <prefix>/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
534
535
536
3. Remove Koha Install Directories and Configuration Files
537
   Don't forget about any crontab entries
538
539
540
Tested on the following operating environments
541
=================================================================
542
  - Ubuntu Precise Pangolin 12.04
543
544
545
Installer Bug reports
546
=================================================================
547
  Please log any installer bug reports at
548
  http://bugs.koha-community.org
549
550
551
Other Notes
552
=================================================================
553
This file is part of Koha
554
555
Koha is free software; you can redistribute it and/or modify it
556
under the terms of the GNU General Public License as published by
557
the Free Software Foundation; either version 2 of the License, or
558
(at your option) any later version.
559
560
Koha is distributed in the hope that it will be useful, but
561
WITHOUT ANY WARRANTY; without even the implied warranty of
562
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
563
GNU General Public License for more details.
564
565
You should have received a copy of the GNU General Public License
566
along with Koha; if not, write to the Free Software Foundation:
567
    Free Software Foundation
568
    51 Franklin Street, Fifth Floor
569
    Boston, MA 02110-1301
570
    USA
571
Or visit their website: http://www.fsf.org/
(-)a/INSTALL.ubuntu.lucid (-381 lines)
Lines 1-380 Link Here
1
=============================
2
Installation Guide for Installing Koha on Ubuntu Lucid Lynx (10.04 LTS) 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 Marchp 2012
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 Lucid Lynx 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 Get Koha
44
45
1.3.1 Option A: Download Koha via Git (optional)
46
47
    $ sudo apt-get install git-core git-email
48
    $ git clone git://git.koha-community.org/koha.git kohaclone
49
    $ cd kohaclone
50
    $ git checkout -b myinstall origin
51
52
Note: for more information about Git, please see the Koha Git Usage Guide:
53
54
    http://wiki.koha-community.org/wiki/Version_Control_Using_Git
55
56
1.3.2 Option B: Download Koha from http://download.koha-community.org
57
58
    $ wget http://download.koha-community.org/koha-3.02.00.tar.gz
59
    ( Note: use the latest stable version)
60
61
1.4 Install additional Ubuntu dependencies
62
63
IMPORTANT:  You should only use CPAN for Perl dependencies which are NOT
64
            available from the package maintainer. You have been warned!
65
66
Using the ubuntu.packages file included in the Koha source tree,
67
run the following:
68
69
    $ sudo dpkg --set-selections < install_misc/ubuntu.packages
70
71
Now start dselect (you may need to 'sudo apt-get install dselect'):
72
73
    $ sudo dselect
74
75
Choose [I]nstall and accept packages to be installed (hit return)
76
77
(may take a while)
78
79
Choose [C]onfigure, [R]emove and [Q]uit until dselect has completed.
80
81
Note: If you are installing on an older version of Ubuntu, not all of the
82
      packages listed in ubuntu.packages may be available as packages.  You
83
      will want to verify which ones are installed and which ones not.
84
      This can be done by running the following command:
85
86
    $ install_misc/ubuntu-pkg-check.sh | grep none
87
88
When tracking down any "(none)" results, note that sometimes Ubuntu does the
89
right thing and installs a later, differently named version of the package in
90
place.  To see if this is happening, it is useful to run a command like:
91
92
    $ dpkg --get-selections | grep [base_package_name]
93
94
1.5 Install Perl dependencies that aren't packaged into Ubuntu Lucid Lynx
95
sources
96
97
Run the following command:
98
99
    $ sudo cpan HTTP::OAI Locale::Currency::Format Memoize::Memcached \
100
                PDF::API2::Simple Storable Text::CSV::Encoded CHI \
101
                CHI::Driver::Memcached
102
103
Note: you may need to run CPAN initialization if you've not run cpan
104
before:
105
106
    /etc/perl/CPAN/Config.pm initialized.
107
108
    CPAN is the world-wide archive of perl resources. It consists of about
109
    100 sites that all replicate the same contents all around the globe.
110
    Many countries have at least one CPAN site already. The resources
111
    found on CPAN are easily accessible with the CPAN.pm module. If you
112
    want to use CPAN.pm, you have to configure it properly.
113
114
    If you do not want to enter a dialog now, you can answer 'no' to this
115
    question and I'll try to autoconfigure. (Note: you can revisit this
116
    dialog anytime later by typing 'o conf init' at the cpan prompt.)
117
118
    Are you ready for manual configuration? [yes]
119
120
When the configuration is completed CPAN will install the Perl modules.
121
122
2. Configuration of dependencies
123
124
2.1 Update root MySQL password (if dselect didn't do it for you already)
125
126
    $ sudo mysqladmin password <password>
127
128
2.2 Create the Koha database
129
130
    Create the database and user with associated privileges:
131
132
    $ mysqladmin -uroot -p<password> create <kohadatabasename>
133
    $ mysql -uroot -p<password>
134
135
    Welcome to the MySQL monitor.  Commands end with ; or \g.
136
    Your MySQL connection id is 22
137
    Server version: 5.0.32-Debian_7etch3-log Debian etch distribution
138
139
    Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
140
141
    mysql> grant all on <kohadatabasename>.* to '<kohadatabaseuser>'@'localhost' identified by '<kohadatabaseuserpassword>';
142
    Query OK, 0 rows affected (0.00 sec)
143
144
    mysql> flush privileges;
145
    Query OK, 0 rows affected (0.00 sec)
146
147
    mysql> quit
148
149
2.3 Test your SAX Parser and correct where necessary
150
151
    You must be sure you're using the XML::LibXML SAX parser, not Expat or
152
    PurePerl, both of which have outstanding bugs with pre-composed
153
    characters. You can test your SAX parser by running:
154
155
    $ cd koha
156
    $ misc/sax_parser_print.pl
157
158
    You should see something like::
159
160
    XML::LibXML::SAX::Parser=HASH(0x81fe220)
161
162
    If you're using PurePerl or Expat, you'll need to edit your
163
    ini file, typically located at:
164
165
    /etc/perl/XML/SAX/ParserDetails.ini
166
167
    You will need to move the entire section for '[XML::LibXML::SAX::Parser]'
168
    to the bottom of the ini file.
169
170
3. Run the Koha installer
171
172
    $ perl Makefile.PL
173
    ( answer questions )
174
    $ make
175
    $ make test
176
    $ sudo make install
177
178
4. Configure and start Apache
179
    $ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha
180
    (note that the path to koha-httpd.conf may be different depending on your
181
    installation choices)
182
183
Add the following lines to /etc/apache2/ports.conf:
184
185
    Listen 80
186
    Listen 8080
187
188
If not running named virtual hosts (The default koha installation does not use
189
named virtual hosts.), comment out the following line:
190
191
    NameVirtualHost *:80
192
193
Run the following commands:
194
195
    $ sudo a2enmod rewrite deflate
196
    $ sudo a2ensite koha
197
    $ sudo apache2ctl restart
198
199
Note: you may still see the usual Apache default site if your VirtualHost
200
configuration isn't correct.  The command "sudo a2dissite default" may be a
201
quick fix, but may have side-effects.  See the Apache HTTPD manual section on
202
virtual hosts for full instructions.
203
204
5. Configure and start Zebra
205
206
Note: it's recommended that you daemonize the Zebra process and add it to your
207
startup profile. For a non-production test/development installation, running
208
Zebra from the command line can be useful. Pick from the two available options
209
below, or roll your own :-)
210
211
Note: it's also recommended that you create a Koha system user, which you will
212
have specified during the install process. Alternatively, Zebra can be
213
configured to run as the root user.
214
215
To add a user do:
216
217
    $ sudo adduser koha
218
219
Option 1: run the Zebra processes from the command line:
220
221
5.1.1 Zebra Search Server
222
223
This process send responses to search requests sent by Koha or
224
Z39.50/SRU/SRW clients.
225
226
    $ sudo -u ${KOHA_USER} zebrasrv -f /etc/koha/koha-conf.xml
227
    (note that the path to koha-conf.xml may be different depending on your
228
    installation choices)
229
230
Note: the user you run Zebra as will be the only user with write permission
231
      on the Zebra index; in development mode, you may wish to use your
232
      system user.
233
234
5.1.2 Zebra Indexer
235
236
Added/updated/deleted records in Koha MySQL database must be indexed
237
into Zebra. A specific script must be launched each time a bibliographic
238
or an authority record is edited.
239
240
    $ sudo -u ${KOHA_USER} misc/migration_tools/rebuild_zebra -z -b -a
241
    NOTE: This script should be run as the kohauser (the default is 'koha').
242
243
Option 2: run the Zebra process as a daemon, and add to startup process:
244
245
Note that references to $SCRIPT_DIR refer to the directory where
246
Koha's command-line scripts are installed, e.g., /usr/share/koha/bin.
247
248
5.2.1 Zebra Search Server
249
250
    $ sudo ln -s ${SCRIPT_DIR}/koha-zebra-ctl.sh  /etc/init.d/koha-zebra-daemon
251
    (Note: ${SCRIPT_DIR} is /usr/share/koha/bin/ by default in a standard install)
252
    $ sudo update-rc.d koha-zebra-daemon defaults
253
    ( Note: see man chkconfig(8) on other distros )
254
255
    $ sudo ${SCRIPT_DIR}/koha-zebra-ctl.sh start
256
257
5.2.2 Zebra Indexer
258
259
Add an entry in Koha user crontab to scheduled added/updated/deleted records
260
indexing by Zebra with this command:
261
262
  <path/to/koha>/misc/migration_tools/rebuild_zebra -z -b -a
263
264
See check misc/cronjobs/crontab.example for usage examples.
265
NOTE: This job should be setup under the kohauser (the default is 'koha').
266
267
You can also configure zebra-indexing as an background daemon, see http://wiki.koha-community.org/wiki/Background_indexing_with_Zebra
268
269
6. Run the Web Installer, populate the database, initial configuration of settings
270
271
    Point your browser to http://<servername>:8080/
272
273
    It should redirect you to the Web Installer where you can continue the setup.
274
    You can install the sample data for libraries, patrons, etc. via the Web Installer
275
276
7. What next?
277
278
    Once the installer has completed, you can import and index MARC records from the
279
    command line thusly (Note: you can also use the 'Stage MARC records for import' from
280
    the Tools area of Koha's Staff Client to import a batch of MARC records):
281
282
    $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml
283
      (note: use the correct path to your koha-conf.xml)
284
285
7.1 Import:
286
    Bibliographic data in MARC21 format
287
    $ misc/migration_tools/bulkmarcimport.pl -file /path/to/marc.iso2709
288
    Authority data in MARC21 format
289
    $ misc/migration_tools/bulkauthimport.pl -file /path/to/auth.iso2709
290
291
7.2 Fast Index:
292
    $ misc/migration_tools/rebuild_zebra.pl -b -w
293
294
    Once the indexing has completed, you will be able to search for records in your system.
295
    NOTE: This script should be run as the kohauser (the default is 'koha').
296
297
7.3 Schedule regular index updates
298
299
    You need to run rebuild_zebra.pl -b -a -z as a regular cron job in orde to pick up new bibs
300
    and items as you add them. Check misc/cronjobs/crontab.example for usage examples. See 7.0 above.
301
    NOTE: This job should be setup under the kohauser (the default is 'koha').
302
303
    You can also indexing in background, see 5.2.2 above
304
305
7.4 To enable public Z39.50/SRU servers, you'll need to edit your koha-conf.xml and
306
    change the <listen> options to listen on a TCP port; then restart the zebra daemon.
307
308
UPGRADE
309
=======
310
If you are running in another language other than english, please
311
switch to english before doing the upgrade, the templating system has
312
changed and the templates will need to be regenerated.
313
Once you have upgraded, please regenerate your templates in your
314
chosen languages.
315
316
If you are upgrading from a previous installation of Koha 3.x, you can
317
use the following:
318
319
 ./koha_perl_deps.pl -u -m # to identify new Perl dependencies
320
321
Install any missing modules
322
IMPORTANT: Koha 3.6.x uses Template::Toolkit, this must be installed
323
before the webinstaller can run
324
325
 sudo apt-get install libtemplate-perl
326
327
Koha 3.4.x or later no longer stores items in biblio records so
328
if you are upgrading from an older version as part of the
329
upgrade you will need to do the following two steps, they can take a
330
long time (several hours) to complete for large databases
331
332
 misc/maintenance/remove_items_from_biblioitems.pl --run
333
 misc/migration_tools/rebuild_zebra.pl -b -r
334
335
Uninstall Instructions
336
=============================
337
1) Stop Services:
338
   $ sudo a2dissite koha
339
   $ sudo rm /etc/apache2/sites-available/koha
340
   $ sudo apache2ctl restart
341
342
   $ sudo update-rc.d koha-zebra-daemon remove
343
   $ sudo rm /etc/init.d/koha-zebra-daemon
344
345
2) Remove Database and Indexes
346
347
   # MySQL
348
   $ mysql -u<kohauser> -p<kohapassword>
349
   > drop database koha;
350
351
   # Zebra Indexes
352
   $ zebraidx -c <prefix>/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
353
   $ zebraidx -c <prefix>/etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
354
355
3) Remove Koha Install Directories and Configuration Files
356
   Don't forget about any crontab entries
357
358
Tested on the following operating environments
359
==============================================
360
- Ubuntu Jaunty Jackalope 9.04
361
362
Installer Bug reports
363
=====================
364
Please log any installer bug reports at http://bugs.koha-community.org
365
366
Other Notes
367
=====================
368
This file is part of Koha
369
370
Koha is free software; you can redistribute it and/or modify it under the
371
terms of the GNU General Public License as published by the Free Software
372
Foundation; either version 2 of the License, or (at your option) any later
373
version.
374
375
Koha is distributed in the hope that it will be useful, but WITHOUT ANY
376
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
377
A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
378
You should have received a copy of the GNU General Public License along
379
with Koha; if not, write to the Free Software Foundation, Inc.,
380
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
381
- 

Return to bug 7764