Bug 6966: Offline Circ Help
[wip/koha-chris_n.git] / INSTALL.debian
1 =============================
2 Installation Guide for Installing Koha on Debian
3 =============================
4
5 Some parts copyright 2010 Chris Nighswonger
6 Some parts copyright 2011 MJ Ray and software.coop
7
8 Feedback/bug reports: Koha Developer's List:
9 http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
10
11 This document last modified: 2011-06-19
12
13 Installation Instructions
14 =============================
15
16 All commands can be performed as a system user with sudo privileges,
17 as indicated or by running the command directly as root.
18
19 1. Prepare System and Install Dependencies
20
21 1.1 Install Debian via Business Card CD
22
23     See http://www.debian.org/CD/netinst/
24
25 1.2 Set up Indexdata apt sources for Yaz and Zebra packages
26
27 See the instructions from indexdata at
28 http://ftp.indexdata.com/pub/debian/README
29
30 At the time of writing, you need to create
31 /etc/apt/sources.list.d/indexdata.list containing the following:
32
33     # Index Data
34     deb http://ftp.indexdata.dk/debian squeeze main
35     deb-src http://ftp.indexdata.dk/debian squeeze main
36
37 and add their archive signing key to your system:
38
39     $ wget -O- http://ftp.indexdata.dk/debian/indexdata.asc | sudo apt-key add -
40
41 Finally, update your apt sources:
42     $ sudo apt-get update
43
44 1.3 Get Koha
45 Choose one of these options:
46
47 1.3.1 Option A: Download Koha via Git (optional)
48
49     $ sudo apt-get install git-core git-email
50     $ git clone git://git.koha-community.org/koha.git koha
51     $ cd koha
52     $ git checkout -b myinstall origin
53
54 Note: for more information about Git, please see the Koha Git Usage Guide:
55
56     http://wiki.koha-community.org/wiki/Version_Control_Using_Git
57
58 1.3.2 Option B: Download Koha from http://download.koha-community.org
59
60 Find the latest Koha stable version on http://download.koha-community.org
61 and download it to your server with something like:
62
63     $ wget <URL found on download.koha-community.org>
64
65 1.4 Install additional Debian dependencies
66
67 IMPORTANT:  You should only use CPAN for Perl dependencies which are NOT
68             available from the package maintainer. You have been warned!
69
70 Installing all necessary Debian packages, MySQL Server,
71 Zebra and all Debian packaged Perl module required by Koha:
72
73     $ sudo dpkg --set-selections < install_misc/debian.packages
74     $ sudo apt-get dselect-upgrade
75
76 1.5 Install Perl dependencies that aren't packaged into Debian
77
78 Run the following command:
79
80     $ perl koha_perl_deps.pl -m -u
81
82 This will list whether any Perl dependencies are missing or need a
83 later version and whether they are required.  You can then install
84 them another way.  There may be packages on
85 http://debian.koha-community.org or maybe you can build packages
86 yourself or maybe you will need to install them locally with a command
87 similar to
88
89     $ sudo cpan Graphics::Magick
90
91 Note: you may need to run CPAN initialization if you've not run cpan
92 before.  See http://search.cpan.org/~andk/CPAN/lib/CPAN.pm#CONFIGURATION
93
94 When the configuration is completed CPAN will install the Perl modules.
95
96 2. Configuration of dependencies
97
98 2.1 Create the Koha database
99
100  Create the database and user with associated privileges (information inside <> brackets is
101  data you assign specifically to your installation. Do not include the <>'s when entering the commands):
102
103     $ mysqladmin -uroot -p<password> create <kohadatabasename>
104     $ mysql -uroot -p<password>
105
106     Welcome to the MySQL monitor.  Commands end with ; or \g.
107     Your MySQL connection id is 22
108     Server version: 5.0.51a-24 (Debian)
109
110     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
111
112     mysql> grant all on <kohadatabasename>.* to '<kohadatabaseuser>'@'localhost' identified by '<kohadatabaseuserpassword>';
113     Query OK, 0 rows affected (0.00 sec)
114
115     mysql> flush privileges;
116     Query OK, 0 rows affected (0.00 sec)
117
118     mysql> quit
119
120 You may want to document the database name, the database username, and the database password you just set.
121 Step 3 will require them.
122
123 2.2 Test your SAX Parser and correct where necessary
124
125 You must be sure you're using the XML::LibXML SAX parser, not Expat or
126 PurePerl, both of which have outstanding bugs with pre-composed characters.
127 You can test your SAX parser by running:
128
129     $ cd koha
130     $ misc/sax_parser_print.pl 
131
132 You should see something like:
133
134     XML::LibXML::SAX::Parser=HASH(0x81fe220)
135
136 If you are configured to use PurePerl or Expat, the script will say you have a problem and 
137 you'll need to edit your ini file to correct it.
138
139 The file is typically located at:
140
141     /etc/perl/XML/SAX/ParserDetails.ini
142
143 The correct parser entry will need to be moved to the bottom of the file.
144 The following is the entry you are looking for:
145
146     [XML::LibXML::SAX::Parser]
147         http://xml.org/sax/features/namespaces = 1
148
149 2.3 Create your Koha system user (if you haven't created one already)
150
151     $ sudo adduser koha
152
153 You can substitute any username for "koha," just be sure to write it down, you will need to know what it is in step 3.
154
155 3. Run the Koha installer
156
157     $ perl Makefile.PL
158       ( answer questions )
159     $ make
160     $ make test
161     $ sudo make install
162
163 3.1 Export the environment variables
164 Make install will tell you what the proper path for these environment variables is.
165 In case you missed it at the end of make install, here are some examples:
166
167 Example (for standard install):
168     $ export KOHA_CONF=/etc/koha/koha-conf.xml
169     $ export PERL5LIB=/usr/share/koha/lib
170
171 Example (for dev install. These paths are set during Makefile.PL.):
172     $ export KOHA_CONF=/path/to/your/koha-conf.xml
173     $ export PERL5LIB=/path/to/koha/lib
174
175 4. Configure and start Apache
176     $ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha
177 (note that the path to koha-httpd.conf may be different if you chose a dev install)
178
179 Add the following lines to /etc/apache2/ports.conf:
180
181     Listen 80
182     Listen 8080
183
184 Run the following commands:
185
186     $ sudo a2enmod rewrite deflate
187     $ sudo a2ensite koha
188     $ sudo apache2ctl restart
189
190 Note: you may still see the usual Apache default site if your VirtualHost
191       configuration isn't correct.  If Koha is the only web application running on the server,
192       the command "sudo a2dissite default" may be a quick fix. For servers running other sites
193       alongside Koha, see the Apache HTTPD manual section on virtual hosts for full
194       instructions (http://httpd.apache.org/docs/2.2/vhosts/).
195
196 5. Run the Web Installer, populate the database, initial configuration of settings
197
198 Point your browser to http://<servername>:8080/
199
200 Note: <servername> is (usually) the IP of your server, or localhost (if you are connecting
201       from the same machine Koha is installed on. You can verify the location by checking 
202       the VirtualHost settings for both the opac and intranet virtual hosts in koha-httpd.conf
203
204 Koha will redirect you to the Web Installer where you can continue the setup. You will be prompted to enter in your DATABASE username and password. It is through this interface 
205 that 
206 you can install the sample data for libraries, patrons, and much more.
207
208 Be aware that removing sample data at a later time (when you may want to take the 
209 server into production) may not be easy, and if your intent is to take this 
210 install from testing to production, go with minimal sample data (no patrons or bibliographic records).
211
212 6. Configure and start Zebra
213
214 Note: it's recommended that you daemonize the Zebra process and add it to your
215       startup profile. For a non-production test/development installation, running
216       Zebra from the command line can be useful. Pick one of the options below (or roll your own).
217
218 Note: it's also recommended that you create a Koha system user, which you will
219       have specified during the install process. Alternatively, Zebra can be
220       configured to run as the root user.
221
222 Option 1: run the Zebra processes from the command line (manual indexing):
223
224 6.1.1 Zebra Search Server
225
226 This process send responses to search requests sent by Koha or
227 Z39.50/SRU/SRW clients.
228
229     $ sudo -u <kohauser> zebrasrv -f /etc/koha/koha-conf.xml
230     (note that the path to koha-conf.xml may be different if you chose a dev install, and that
231     <kohauser> refers to the user you set up in step 2.3)
232
233 Note: the user you run Zebra as will be the only user with write permission
234       on the Zebra index; in development mode, you may wish to use your
235       system user.
236
237
238 6.1.2 Zebra Indexer
239
240 Added/updated/deleted records in Koha MySQL database must be indexed
241 into Zebra. A specific script must be launched each time a bibliographic
242 or an authority record is edited.
243
244     $ sudo -u <kohauser> misc/migration_tools/rebuild_zebra.pl -z -b -a
245
246 Note: This script should be run as the kohauser (the default is 'koha', but
247 this is the user you set up in step 2.3).
248
249 Option 2: run the Zebra process as a daemon (automatic indexing):
250
251 Note: References to <script_dir> refer to the directory where
252       Koha's command-line scripts are installed, the path
253       is /usr/share/koha/bin/ by default in a standard install.
254
255 6.2.1 Zebra Search Server
256
257     $ sudo ln -s <script_dir>/koha-zebra-ctl.sh  /etc/init.d/koha-zebra-daemon
258     (Note: <script_dir> is /usr/share/koha/bin/ by default in a standard install)
259     $ sudo update-rc.d koha-zebra-daemon defaults
260
261     $ sudo <script_dir>/koha-zebra-ctl.sh start
262     (Note: <script_dir> is /usr/share/koha/bin/ by default in a standard install)
263
264
265 6.2.2 Zebra Indexer
266
267 Add an entry in Koha user crontab to process scheduled added/updated/deleted records
268 indexing by Zebra. <script_dir>cronjobs/crontab.example contains examples for these cron jobs (and many more).
269
270 NOTE: The cronjobs should be setup under the kohauser (the default is 'koha', but
271 this is the user you set up in step 2.3).
272
273 Edit the crontab for the koha user by running
274     $ sudo -u <kohauser> crontab -e
275
276 For Zebra indexing, you are looking for the example that begins with
277     
278     # ZEBRA INDEX UPDATES with -z option, incremental index updates throughout the day
279     # for both authorities and bibs
280
281 It may be easiest to copy/paste the example into your own crontab and modify as necessary.
282
283
284 7. What next?
285
286     Once the installer has completed, you can import and index MARC records from the
287     command line thusly (Note: you can also use the 'Stage MARC records for import' from
288     the Tools area of Koha's Staff Client to import a batch of MARC records):
289
290     $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml
291       (note: use the correct path to your koha-conf.xml)
292
293 7.1 Import:
294
295 Bibliographic data in MARC21 format
296
297     $ misc/migration_tools/bulkmarcimport.pl -file /path/to/marc.iso2709
298
299 Authority data in MARC21 format
300
301     $ misc/migration_tools/bulkmarcimport.pl -a -file /path/to/auth.iso2709
302
303 7.2 Fast Index:
304     $ misc/migration_tools/rebuild_zebra.pl -b -w
305
306     Once the indexing has completed, you will be able to search for records in your system.
307     NOTE: This script should be run as the kohauser (the default is 'koha', this is the user we set up in step 2.3).
308
309 7.3 Schedule regular index updates
310     You need to run rebuild_zebra.pl -b -a -z as a regular cron job in orde to pick up new bibs
311     and items as you add them. Check misc/cronjobs/crontab.example for usage examples. See 7.0 above.
312     NOTE: This job should be setup under the kohauser (the default is 'koha', this is the user we set up in step 2.3).
313
314 7.4 To enable public Z39.50/SRU servers, you'll need to edit your koha-conf.xml and
315     change the <listen> options to listen on a TCP port; then restart the zebra daemon.
316
317 UPGRADE
318 =======
319 If you are running in another language other than english, please
320 switch to english before doing the upgrade, the templating system has
321 changed and the templates will need to be regenerated.
322 Once you have upgraded, please regenerate your templates in your
323 chosen languages.
324
325 If you are upgrading from a previous installation of Koha 3.x, you can
326 use the following:
327
328  ./koha_perl_deps.pl -u -m # to identify new Perl dependencies
329
330 Install any missing modules
331 IMPORTANT: Koha 3.4.x uses Template::Toolkit, this must be installed
332 before the webinstaller can run
333
334  sudo apt-get install libtemplate-perl
335
336  perl Makefile.PL --prev-install-log /path/to/koha-install-log
337  make
338  make test
339  sudo make upgrade
340
341 Koha 3.4.x no longer stores items in biblio records so as part of the
342 upgrade you will need to do the following two steps, they can take a
343 long time (several hours) to complete for large databases
344
345  misc/maintenance/remove_items_from_biblioitems.pl --run
346  misc/migration_tools/rebuild_zebra.pl -b -r
347
348 Uninstall Instructions
349 =============================
350 1) Stop Services:
351    $ sudo a2dissite koha
352    $ sudo rm /etc/apache2/sites-available/koha
353    $ sudo apache2ctl restart
354
355    $ sudo update-rc.d koha-zebra-daemon remove
356    $ sudo rm /etc/init.d/koha-zebra-daemon
357
358 2) Remove Database and Indexes
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
368 3) Remove Koha Install Directories and Configuration Files
369    Don't forget about any crontab entries
370
371 Tested on the following operating environments
372 ==============================================
373 - Debian Lenny 5.0
374 - Debian Squeeze 6.0
375
376 Other Notes
377 =====================
378 This file is part of Koha
379
380 Koha is free software; you can redistribute it and/or modify it under the
381 terms of the GNU General Public License as published by the Free Software
382 Foundation; either version 2 of the License, or (at your option) any later
383 version.
384
385 Koha is distributed in the hope that it will be useful, but WITHOUT ANY
386 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
387 A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
388 You should have received a copy of the GNU General Public License along with
389 Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
390 Suite 330, Boston, MA  02111-1307 USA
391