Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 393 lines (259 sloc) 12.97 kB
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
1 =============================
2 Installation Guide for Installing Koha on Debian Etch with MySQL 5
3 =============================
4
5 Copyright (C) 2007, LibLime
6
7 Maintainer: Joshua Ferraro (jmf AT liblime DOT com)
dcb3858 Several important commits:
Joshua Ferraro authored
8 Feedback/bug reports: jmf AT liblime DOT com
844f1fa updates to some of the finer points of the install process on Etch
Joshua Ferraro authored
9 This document last modified: 29 December 2007
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
10
11 Installation Instructions
12 =============================
13
14 All commands can be performed as a system user with sudo privileges,
77c6fcc fixes to README.debian
Joshua Ferraro authored
15 as indicated or by running the command directly as root.
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
16
9c25d63 improvements to INSTALL.debian, adding Symbols for currencies adding …
Joshua Ferraro authored
17 1. Prepare System and Install Dependencies
18
19 1.1 Install Debian Etch via Businesscard CD
20
21 See http://www.debian.org/releases/etch/debian-installer/
22
23 1.2 Set up your locale
24
77c6fcc fixes to README.debian
Joshua Ferraro authored
25 Your locale should be set to UTF-8, as should Apache2 and MySQL 5.
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
26 This step is VERY IMPORTANT for a UNICODE compliant system. Please
27 read over the following document carefully:
28
29 http://wiki.koha.org/doku.php?id=encodingscratchpad
30
9c25d63 improvements to INSTALL.debian, adding Symbols for currencies adding …
Joshua Ferraro authored
31 IMPORTANT: You _MUST_ follow all the steps outlined there for
32 Apache2, MySQL 5, etc. BEFORE you install Koha.
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
33
9c25d63 improvements to INSTALL.debian, adding Symbols for currencies adding …
Joshua Ferraro authored
34 1.3 Set up apt sources for Git, Yaz and Zebra packages
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
35
36 Edit your /etc/apt/sources.list file and add the following:
37
38 # Index Data
39 deb http://ftp.indexdata.dk/debian etch main
40 deb-src http://ftp.indexdata.dk/debian etch main
41
42 # Backports
43 deb http://www.backports.org/debian etch-backports main contrib non-free
44
45 Backports packages are signed with a key you can install as follows:
46
b74320e @fredericd Some tweaks for Debian Etch install procedure
fredericd authored
47 $ sudo apt-get update
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
48 $ sudo apt-get install debian-backports-keyring
49
50 The Index Data packages are signed with a key you can install as follows:
51
52 $ wget http://ftp.indexdata.dk/debian/indexdata.asc
53 $ sudo apt-key add indexdata.asc
54
55 Run the following command to update your system:
56
57 $ sudo apt-get update
58 $ sudo apt-get -t etch-backports install git-core git-email
59 $ sudo apt-get install yaz idzebra-2.0 idzebra-2.0-doc
60
9c25d63 improvements to INSTALL.debian, adding Symbols for currencies adding …
Joshua Ferraro authored
61 1.4 Get Koha
844f1fa updates to some of the finer points of the install process on Etch
Joshua Ferraro authored
62
9c25d63 improvements to INSTALL.debian, adding Symbols for currencies adding …
Joshua Ferraro authored
63 1.4.1 Option A: Download Koha via Git (optional)
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
64
65 $ git clone git://git.koha.org/pub/scm/koha.git kohaclone
66 $ cd kohaclone
67 $ git checkout -b myinstall origin
68
69 Note: for more information about Git, please see the Koha Git Usage Guide:
70
eedb944 updating INSTALL and INSTALL.debian
Joshua Ferraro authored
71 http://wiki.koha.org/doku.php?id=en:development:git_usage
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
72
9c25d63 improvements to INSTALL.debian, adding Symbols for currencies adding …
Joshua Ferraro authored
73 1.4.2 Option B: Download Koha from http://download.koha.org
74
85cfcf5 updating installation docs
Joshua Ferraro authored
75 $ wget http://download.koha.org/koha-3.00.00-beta.tar.gz
9c25d63 improvements to INSTALL.debian, adding Symbols for currencies adding …
Joshua Ferraro authored
76 ( Note: use the latest stable version)
844f1fa updates to some of the finer points of the install process on Etch
Joshua Ferraro authored
77
9c25d63 improvements to INSTALL.debian, adding Symbols for currencies adding …
Joshua Ferraro authored
78 1.5 Install additional Debian dependencies
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
79
9c25d63 improvements to INSTALL.debian, adding Symbols for currencies adding …
Joshua Ferraro authored
80 IMPORTANT: You should only use CPAN for Perl dependencies which are NOT
81 available from the package maintainer. You have been warned!
d3dc1ad Updating README.debian
Chris Nighswonger authored
82
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
83 Using the debian.packages file included in the Koha source tree,
84 run the following:
85
86 $ sudo dpkg --set-selections < install_misc/debian.packages
87
88 Now start dselect:
89
90 $ sudo dselect
91
92 Choose [I]nstall and accept packages to be installed (hit return)
93
94 (may take a while)
95
96 Choose [C]onfigure, [R]emove and [Q]uit until dselect has completed.
97
9c25d63 improvements to INSTALL.debian, adding Symbols for currencies adding …
Joshua Ferraro authored
98 1.6 Install Perl dependencies that aren't packaged into Debian Etch
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
99 sources
100
101 Run the following command:
102
8f82439 important: DBD::mysql 4.004 or later required
Galen Charlton authored
103 $ sudo cpan MARC::Record Class::Accessor MARC::Charset MARC::File::XML \
104 Net::Z3950::ZOOM HTML::Template::Pro MARC::Crosswalk::DublinCore \
105 PDF::Reuse PDF::Reuse::Barcode Data::ICal GD::Barcode::UPCE \
106 XML::RSS Algorithm::CheckDigits::M43_001 Biblio::EndnoteStyle POE Schedule::At
107
108 There is a known but benign error in the test case for Barcode::Code128,
109 which is required by PDF::Reuse::Barcode. If this module is not installed,
110 you can do a forced installation of Barcode::Code128.
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
111
112 Note: you may need to run CPAN initialization if you've not run cpan
113 before:
114
115 /etc/perl/CPAN/Config.pm initialized.
116
117 CPAN is the world-wide archive of perl resources. It consists of about
118 100 sites that all replicate the same contents all around the globe.
119 Many countries have at least one CPAN site already. The resources
120 found on CPAN are easily accessible with the CPAN.pm module. If you
121 want to use CPAN.pm, you have to configure it properly.
122
123 If you do not want to enter a dialog now, you can answer 'no' to this
124 question and I'll try to autoconfigure. (Note: you can revisit this
125 dialog anytime later by typing 'o conf init' at the cpan prompt.)
126
127 Are you ready for manual configuration? [yes]
128
129 When the configuration is completed CPAN will install the Perl modules.
130
131 2. Configuration of dependencies
132
133 2.1 Update root MySQL password (if dselect didn't do it for you already)
134
135 $ sudo mysqladmin password <password>
136
137 2.2 Create the Koha database
138
844f1fa updates to some of the finer points of the install process on Etch
Joshua Ferraro authored
139 Create the database and user with associated privileges:
140
33bc56f fixed mysqladmin invocation in INSTALL.debian
Galen Charlton authored
141 $ mysqladmin -uroot -p<password> create <kohadatabasename>
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
142 $ mysql -uroot -p<password>
143
144 Welcome to the MySQL monitor. Commands end with ; or \g.
145 Your MySQL connection id is 22
146 Server version: 5.0.32-Debian_7etch3-log Debian etch distribution
147
148 Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
149
d3dc1ad Updating README.debian
Chris Nighswonger authored
150 mysql> grant all on <kohadatabasename>.* to '<kohadatabaseuser>'@'localhost' identified by '<kohadatabaseuserpassword>';
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
151 Query OK, 0 rows affected (0.00 sec)
152
153 mysql> flush privileges;
154 Query OK, 0 rows affected (0.00 sec)
155
156 mysql> quit
157
eedb944 updating INSTALL and INSTALL.debian
Joshua Ferraro authored
158 2.3 Test your SAX Parser and correct where necessary
159
160 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:
161
9c25d63 improvements to INSTALL.debian, adding Symbols for currencies adding …
Joshua Ferraro authored
162 $ cd koha
eedb944 updating INSTALL and INSTALL.debian
Joshua Ferraro authored
163 $ misc/sax_parser_print.pl
164
165 You should see something like::
166
167 XML::LibXML::SAX::Parser=HASH(0x81fe220)
168
169 If you're using PurePerl or Expat, you'll need to edit your
170 ini file, typically located at:
171
172 /etc/perl/XML/SAX/ParserDetails.ini
173
174 2.4 Create test database in order to install DBD::mysql
8f82439 important: DBD::mysql 4.004 or later required
Galen Charlton authored
175
176 In order to handle UTF-8 correctly, Koha requires at least version 4.004
177 of the DBD::mysql Perl module. However, Debian Etch has a stable package
178 only for version 3.0008, so it is necessary to install the module from CPAN.
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 ''
144d65e improved instructions for installing DBD::mysql
Galen Charlton authored
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).
8f82439 important: DBD::mysql 4.004 or later required
Galen Charlton authored
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
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
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
9b14c38 adding ports information
Joshua Ferraro authored
247 Add the following lines to /etc/apache2/ports.conf:
248
249 Listen 80
250 Listen 8080
251
252 Run the following commands:
253
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
254 $ sudo a2enmod rewrite
77c6fcc fixes to README.debian
Joshua Ferraro authored
255 $ sudo a2ensite koha
256 $ sudo apache2ctl restart
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
257
dcb3858 Several important commits:
Joshua Ferraro authored
258 5. Configure and start Zebra
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
259
dcb3858 Several important commits:
Joshua Ferraro authored
260 Note: it's recommended that you daemonize the Zebra process and add it to your
261 startup profile. For a non-production test/development installation, running
262 Zebra from the command line can be useful. Pick from the two available options
263 below, or roll your own :-)
264
265 Note: it's also recommended that you create a Koha system user, which you will
266 have specified during the install process. Alternatively, Zebra can be
267 configured to run as the root user.
268
269 Option 1: run the Zebra processes from the command line:
270
271 Zebra Server:
9441380 more updates to README.debain
Joshua Ferraro authored
272 $ sudo -u ${KOHA_USER} zebrasrv -f /etc/koha/koha-conf.xml
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
273 (note that the path to koha-conf.xml may be different depending on your
274 installation choices)
275
85092da Warning: Big Commit. Fixing Virtual Shelves
Joshua Ferraro authored
276 Note: the user you run Zebra as will be the only user with write permission
277 on the Zebra index; in development mode, you may wish to use your system
278 user.
279
dcb3858 Several important commits:
Joshua Ferraro authored
280 Zebraqueue Daemon:
9441380 more updates to README.debain
Joshua Ferraro authored
281 $ sudo -u ${KOHA_USER} misc/bin/zebraqueue_daemon.pl
dcb3858 Several important commits:
Joshua Ferraro authored
282
85092da Warning: Big Commit. Fixing Virtual Shelves
Joshua Ferraro authored
283 Note: if you are running in this mode, you may wish to defer starting the
284 zebraqueue until you've run the web installer (see below).
285
dcb3858 Several important commits:
Joshua Ferraro authored
286 Option 2: run the Zebra processes as daemons, and add to startup process:
287
e6ee69b various installer changes
Galen Charlton authored
288 Note that references to $SCRIPT_DIR refer to the directory where
289 Koha's command-line scripts are installed, e.g., /usr/share/koha/bin.
290
dcb3858 Several important commits:
Joshua Ferraro authored
291 Zebra Server:
e6ee69b various installer changes
Galen Charlton authored
292 $ sudo ln -s ${SCRIPT_DIR}/koha-zebra-ctl.sh /etc/init.d/koha-zebra-daemon
9441380 more updates to README.debain
Joshua Ferraro authored
293 (Note: ${SCRIPT_DIR} is /usr/share/koha/bin/ by default in a standard install)
77c6fcc fixes to README.debian
Joshua Ferraro authored
294 $ sudo update-rc.d koha-zebra-daemon defaults
dcb3858 Several important commits:
Joshua Ferraro authored
295 ( Note: see man chkconfig(8) on other distros )
77c6fcc fixes to README.debian
Joshua Ferraro authored
296
297 $ sudo ${SCRIPT_DIR}/koha-zebra-ctl.sh start
dcb3858 Several important commits:
Joshua Ferraro authored
298
299 Zebraqueue Daemon:
e6ee69b various installer changes
Galen Charlton authored
300 $ sudo ln -s ${SCRIPT_DIR}/koha-zebraqueue-ctl.sh /etc/init.d/koha-zebraqueue-daemon
77c6fcc fixes to README.debian
Joshua Ferraro authored
301 $ sudo update-rc.d koha-zebraqueue-daemon defaults
dcb3858 Several important commits:
Joshua Ferraro authored
302 ( Note: see man chkconfig(8) on other distros )
303
77c6fcc fixes to README.debian
Joshua Ferraro authored
304 $ sudo ${SCRIPT_DIR}/koha-zebraqueue-ctl.sh start
e6ee69b various installer changes
Galen Charlton authored
305
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
306 6. Run the Web Installer, populate the database, initial configuration of settings
307
308 Point your browser to http://<servername>:8080/
309
9c25d63 improvements to INSTALL.debian, adding Symbols for currencies adding …
Joshua Ferraro authored
310 It should redirect you to the Web Installer where you can continue the setup.
311 You can install the sample data for libraries, patrons, etc. via the Web Installer
312
313 7. What next?
314
315 Once the installer has completed, you can import and index MARC records from the
316 command line thusly (Note: you can also use the 'Stage MARC records for import' from
317 the Tools area of Koha's Staff Client to import a batch of MARC records):
318
319 $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml
320 (note: use the correct path to your koha-conf.xml)
321
322 7.1 Import:
323 $ misc/migration-tools/bulkmarcimport.pl -file /path/to/marc.iso2709
324
325 7.2 Fast Index:
326 $ misc/migration-tools/rebuild_zebra.pl -b -w
327
328 Once the indexing has completed, you will be able to search for records in your
329 system. NOTE: if you don't run the Fast Index utility, and you have the zebraqueue
330 daemon running, the indexin process will happen in the background, but it will be
331 orders of magnitude slower.
332
333 To enable the SRU servers, you'll need to edit your koha-conf.xml and change the
334 <listen> options to listen on a TCP port; then restart the zebra daemon.
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
335
6eb3001 adding upgrade instructions to INSTALL and INSTALL.debain
Joshua Ferraro authored
336 UPGRADE
337 =======
338 If you are upgrading from a previous installation of Koha 3, you can
339 use the following:
340
341 perl Makefile.PL --prev-install-log /path/to/koha-install-log
342 make
343 make test
344 sudo make upgrade
345
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
346 Uninstall Instructions
347 =============================
9441380 more updates to README.debain
Joshua Ferraro authored
348 1) Stop Services:
349 $ sudo a2dissite koha
350 $ sudo rm /etc/apache2/sites-available/koha
351 $ sudo apache2ctl restart
352
353 $ sudo update-rc.d koha-zebra-daemon remove
354 $ sudo update-rc.d koha-zebraqueue-daemon remove
355 $ sudo rm /etc/init.d/koha-zebra-daemon
356 $ sudo rm /etc/init.d/koha-zebraqueue-daemon
357
844f1fa updates to some of the finer points of the install process on Etch
Joshua Ferraro authored
358 2) Remove Koha Databases
85092da Warning: Big Commit. Fixing Virtual Shelves
Joshua Ferraro authored
359
360 # MySQL
361 $ mysql -u<kohauser> -p<kohapassword>
362 > drop database koha;
363
364 # Zebra Indexes
365 $ zebraidx -c <prefix>/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
366 $ zebraidx -c <prefix>/etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
367
844f1fa updates to some of the finer points of the install process on Etch
Joshua Ferraro authored
368 3) Remove Koha Install Directories and Configuration Files
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
369
370 Tested on the following operating environments
371 ==============================================
372 - Debian Etch 4.0
373
374 Installer Bug reports
375 =====================
dcb3858 Several important commits:
Joshua Ferraro authored
376 Please send any installer bug reports to jmf AT liblime DOT com
fa212d4 adding debian-specific installation guide
Joshua Ferraro authored
377
378 Other Notes
379 =====================
380 This file is part of Koha
381
382 Koha is free software; you can redistribute it and/or modify it under the
383 terms of the GNU General Public License as published by the Free Software
384 Foundation; either version 2 of the License, or (at your option) any later
385 version.
386
387 Koha is distributed in the hope that it will be useful, but WITHOUT ANY
388 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
389 A PARTICULAR PURPOSE. See the GNU General Public License for more details.
390 You should have received a copy of the GNU General Public License along with
391 Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
392 Suite 330, Boston, MA 02111-1307 USA
Something went wrong with that request. Please try again.