updated links to Git usage wiki page
[wip/koha-chris_n.git] / INSTALL.debian-lenny
1 =============================
2 Installation Guide for Installing Koha on Debian Lenny with MySQL 5
3 =============================
4
5 Some parts copyright 2010 Chris Nighswonger
6
7 Feedback/bug reports: Koha Developer's List:
8 http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
9
10 This document last modified: 19 May 2010
11
12 Installation Instructions
13 =============================
14
15 All commands can be performed as a system user with sudo privileges,
16 as indicated or by running the command directly as root.
17
18 1. Prepare System and Install Dependencies
19
20 1.1 Install Debian Lenny via Businesscard CD
21
22 See http://www.debian.org/releases/lenny/debian-installer/
23
24 1.3 Set up Indexdata apt sources for Yaz and Zebra packages
25
26 Edit your /etc/apt/sources.list file and add the following:
27
28     # Index Data
29     deb http://ftp.indexdata.dk/debian lenny main
30     deb-src http://ftp.indexdata.dk/debian lenny main
31
32 The Index Data packages are signed with a key you can install as follows:
33
34     $ wget http://ftp.indexdata.dk/debian/indexdata.asc
35     $ sudo apt-key add indexdata.asc
36
37 1.4 Get Koha
38
39 1.4.1 Option A: Download Koha via Git (optional)
40
41     $ sudo apt-get install git-core git-email
42     $ git clone git://git.koha-community.org/pub/scm/koha.git kohaclone
43     $ cd kohaclone
44     $ git checkout -b myinstall origin
45
46 Note: for more information about Git, please see the Koha Git Usage Guide:
47
48     http://wiki.koha-community.org/wiki/Version_Control_Using_Git
49
50 1.4.2 Option B: Download Koha from http://download.koha-community.org
51
52 Find the latest Koha stable version on http://download.koha-community.org
53 and get it:
54
55     $ wget <URL> found on download.koha-community.org
56
57 1.5 Install additional Debian dependencies
58
59 IMPORTANT:  You should only use CPAN for Perl dependencies which are NOT
60             available from the package maintainer. You have been warned!
61
62 Run shell script installing all necessary Debian packages, MySQL Server,
63 Zebra and all Debian packaged Perl module required by Koha:
64
65     $ sudo install_misc/apt-get-debian-lenny.sh
66
67 1.6 Install Perl dependencies that aren't packaged into Debian Lenny
68 sources
69
70 Run the following command:
71
72     $ sudo cpan Algorithm::CheckDigits SMS::Send HTTP::OAI IPC::Cmd \\
73       Memoize::Memcached PDF::API2::Simple PDF::Table Storable Test::More \\
74       Locale::Currency::Format
75
76 Note: you may need to run CPAN initialization if you've not run cpan
77 before:
78
79     /etc/perl/CPAN/Config.pm initialized.
80     
81     CPAN is the world-wide archive of perl resources. It consists of about
82     100 sites that all replicate the same contents all around the globe.
83     Many countries have at least one CPAN site already. The resources
84     found on CPAN are easily accessible with the CPAN.pm module. If you
85     want to use CPAN.pm, you have to configure it properly.
86     
87     If you do not want to enter a dialog now, you can answer 'no' to this
88     question and I'll try to autoconfigure. (Note: you can revisit this
89     dialog anytime later by typing 'o conf init' at the cpan prompt.)
90     
91     Are you ready for manual configuration? [yes]
92
93 When the configuration is completed CPAN will install the Perl modules.
94
95 2. Configuration of dependencies
96
97 2.1 Update root MySQL password (if dselect didn't do it for you already)
98
99     $ sudo mysqladmin password <password>
100
101 2.2 Create the Koha database
102
103     Create the database and user with associated privileges:
104
105     $ mysqladmin -uroot -p<password> create <kohadatabasename>
106     $ mysql -uroot -p<password>
107     
108     Welcome to the MySQL monitor.  Commands end with ; or \g.
109     Your MySQL connection id is 22
110     Server version: 5.0.51a-24 (Debian)
111     
112     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
113     
114     mysql> grant all on <kohadatabasename>.* to '<kohadatabaseuser>'@'localhost' identified by '<kohadatabaseuserpassword>';
115     Query OK, 0 rows affected (0.00 sec)
116
117     mysql> flush privileges;
118     Query OK, 0 rows affected (0.00 sec)
119
120     mysql> quit
121
122 2.3 Test your SAX Parser and correct where necessary
123
124 You must be sure you're using the XML::LibXML SAX parser, not Expat or 
125 PurePerl, both of which have outstanding bugs with pre-composed characters. 
126 You can test your SAX parser by running:
127
128     $ cd koha
129     $ misc/sax_parser_print.pl 
130
131     You should see something like::
132
133     XML::LibXML::SAX::Parser=HASH(0x81fe220)
134
135     If you're using PurePerl or Expat, you'll need to edit your
136     ini file, typically located at:
137
138     /etc/perl/XML/SAX/ParserDetails.ini
139
140
141 3. Run the Koha installer
142
143     $ perl Makefile.PL
144     ( answer questions )
145     $ make
146     $ make test
147     $ sudo make install
148
149 4. Configure and start Apache
150     $ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha
151     (note that the path to koha-httpd.conf may be different depending on your
152     installation choices)
153
154 Add the following lines to /etc/apache2/ports.conf:
155
156     Listen 80
157     Listen 8080
158
159 Run the following commands:
160
161     $ sudo a2enmod rewrite
162     $ sudo a2ensite koha
163     $ sudo apache2ctl restart
164
165 Note: you may still see the usual Apache default site if your VirtualHost
166 configuration isn't correct.  The command "sudo a2dissite default" may be a
167 quick fix, but may have side-effects.  See the Apache HTTPD manual section on
168 virtual hosts for full instructions.
169
170 5. Configure and start Zebra
171
172 Note: it's recommended that you daemonize the Zebra process and add it to your
173 startup profile. For a non-production test/development installation, running 
174 Zebra from the command line can be useful. Pick from the two available options
175 below, or roll your own :-)
176
177 Note: it's also recommended that you create a Koha system user, which you will
178 have specified during the install process. Alternatively, Zebra can be
179 configured to run as the root user.
180
181 Option 1: run the Zebra processes from the command line:
182
183 1.1 Zebra Search Server
184
185 This process send responses to search requests sent by Koha or
186 Z39.50/SRU/SRW clients.
187
188     $ sudo -u ${KOHA_USER} zebrasrv -f /etc/koha/koha-conf.xml
189     (note that the path to koha-conf.xml may be different depending on your
190     installation choices)
191
192 Note: the user you run Zebra as will be the only user with write permission
193       on the Zebra index; in development mode, you may wish to use your
194       system user.
195
196 1.2 Zebra Indexer
197
198 Added/updated/deleted records in Koha MySQL database must be indexed
199 into Zebra. A specific script must be launched each time a bibliographic
200 or an authority record is edited.
201
202     $ sudo -u ${KOHA_USER} misc/migration_tools/rebuild_zebra -z -b -a
203     NOTE: This script should be run as the kohauser (the default is 'koha').
204
205 Option 2: run automatically Zebra process as a daemon:
206
207 Note that references to $SCRIPT_DIR refer to the directory where
208 Koha's command-line scripts are installed, e.g., /usr/share/koha/bin.
209
210 1.1 Zebra Search Server
211
212     $ sudo ln -s ${SCRIPT_DIR}/koha-zebra-ctl.sh  /etc/init.d/koha-zebra-daemon
213     (Note: ${SCRIPT_DIR} is /usr/share/koha/bin/ by default in a standard install)
214     $ sudo update-rc.d koha-zebra-daemon defaults
215     ( Note: see man chkconfig(8) on other distros )
216
217     $ sudo ${SCRIPT_DIR}/koha-zebra-ctl.sh start
218
219 1.2 Zebra Indexer
220
221 Add an entry in Koha user crontab to scheduled added/updated/deleted records
222 indexing by Zebra with this command:
223
224   <path/to/koha>/misc/migration_tools/rebuild_zebra -z -b -a
225
226 See check misc/cronjobs/crontab.example for usage examples.
227 NOTE: This job should be setup under the kohauser (the default is 'koha').
228
229 6. Run the Web Installer, populate the database, initial configuration of settings
230
231     Point your browser to http://<servername>:8080/
232
233     It should redirect you to the Web Installer where you can continue the setup.
234     You can install the sample data for libraries, patrons, etc. via the Web Installer
235
236 7. What next?
237
238     Once the installer has completed, you can import and index MARC records from the
239     command line thusly (Note: you can also use the 'Stage MARC records for import' from
240     the Tools area of Koha's Staff Client to import a batch of MARC records):
241
242     $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml
243       (note: use the correct path to your koha-conf.xml)
244
245 7.1 Import:
246
247 Bibliographic data in MARC21 format
248
249     $ misc/migration_tools/bulkmarcimport.pl -file /path/to/marc.iso2709
250
251 Authority data in MARC21 format
252
253     $ misc/migration_tools/bulkmarcimport.pl -a -file /path/to/auth.iso2709
254
255 7.2 Fast Index:
256     $ misc/migration_tools/rebuild_zebra.pl -b -w
257
258     Once the indexing has completed, you will be able to search for records in your system.
259     NOTE: This script should be run as the kohauser (the default is 'koha').
260
261 7.3 Schedule regular index updates
262     You need to run rebuild_zebra.pl -b -a -z as a regular cron job in orde to pick up new bibs
263     and items as you add them. Check misc/cronjobs/crontab.example for usage examples. See 7.0 above.
264     NOTE: This job should be setup under the kohauser (the default is 'koha').
265
266 7.4 To enable public Z39.50/SRU servers, you'll need to edit your koha-conf.xml and
267     change the <listen> options to listen on a TCP port; then restart the zebra daemon.
268
269 UPGRADE
270 =======
271 If you are upgrading from a previous installation of Koha 3, you can
272 use the following:
273
274  perl Makefile.PL --prev-install-log /path/to/koha-install-log
275  make
276  make test
277  sudo make upgrade
278
279 Uninstall Instructions
280 =============================
281 1) Stop Services:
282    $ sudo a2dissite koha
283    $ sudo rm /etc/apache2/sites-available/koha
284    $ sudo apache2ctl restart
285
286    $ sudo update-rc.d koha-zebra-daemon remove
287    $ sudo rm /etc/init.d/koha-zebra-daemon
288
289 2) Remove Database and Indexes
290
291    # MySQL
292    $ mysql -u<kohauser> -p<kohapassword>
293    > drop database koha;
294
295    # Zebra Indexes
296    $ zebraidx -c <prefix>/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
297    $ zebraidx -c <prefix>/etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
298
299 3) Remove Koha Install Directories and Configuration Files
300    Don't forget about any crontab entries
301
302 Tested on the following operating environments
303 ==============================================
304 - Debian Lenny 5.0
305
306 Other Notes
307 =====================
308 This file is part of Koha
309
310 Koha is free software; you can redistribute it and/or modify it under the
311 terms of the GNU General Public License as published by the Free Software
312 Foundation; either version 2 of the License, or (at your option) any later
313 version.
314
315 Koha is distributed in the hope that it will be useful, but WITHOUT ANY
316 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
317 A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
318 You should have received a copy of the GNU General Public License along with
319 Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
320 Suite 330, Boston, MA  02111-1307 USA