1 =============================
2 Installation Guide for Installing Koha on Debian
3 =============================
5 Some parts copyright 2010 Chris Nighswonger
6 Some parts copyright 2011 MJ Ray and software.coop
8 Feedback/bug reports: Koha Developer's List:
9 http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
11 This document last modified: 2011-06-19
13 Installation Instructions
14 =============================
16 All commands can be performed as a system user with sudo privileges,
17 as indicated or by running the command directly as root.
19 1. Prepare System and Install Dependencies
21 1.1 Install Debian via Business Card CD
23 See http://www.debian.org/CD/netinst/
25 1.2 Set up Indexdata apt sources for Yaz and Zebra packages
27 See the instructions from indexdata at
28 http://ftp.indexdata.com/pub/debian/README
30 At the time of writing, you need to create
31 /etc/apt/sources.list.d/indexdata.list containing the following:
34 deb http://ftp.indexdata.dk/debian squeeze main
35 deb-src http://ftp.indexdata.dk/debian squeeze main
37 and add their archive signing key to your system:
39 $ wget -O- http://ftp.indexdata.dk/debian/indexdata.asc | sudo apt-key add -
41 Finally, update your apt sources:
45 Choose one of these options:
47 1.3.1 Option A: Download Koha via Git (optional)
49 $ sudo apt-get install git-core git-email
50 $ git clone git://git.koha-community.org/koha.git koha
52 $ git checkout -b myinstall origin
54 Note: for more information about Git, please see the Koha Git Usage Guide:
56 http://wiki.koha-community.org/wiki/Version_Control_Using_Git
58 1.3.2 Option B: Download Koha from http://download.koha-community.org
60 Find the latest Koha stable version on http://download.koha-community.org
61 and download it to your server with something like:
63 $ wget <URL found on download.koha-community.org>
65 1.4 Install additional Debian dependencies
67 IMPORTANT: You should only use CPAN for Perl dependencies which are NOT
68 available from the package maintainer. You have been warned!
70 Installing all necessary Debian packages, MySQL Server,
71 Zebra and all Debian packaged Perl module required by Koha:
73 $ sudo dpkg --set-selections < install_misc/debian.packages
74 $ sudo apt-get dselect-upgrade
76 1.5 Install Perl dependencies that aren't packaged into Debian
78 Run the following command:
80 $ perl koha_perl_deps.pl -m -u
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
89 $ sudo cpan Graphics::Magick
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
94 When the configuration is completed CPAN will install the Perl modules.
96 2. Configuration of dependencies
98 2.1 Create the Koha database
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):
103 $ mysqladmin -uroot -p<password> create <kohadatabasename>
104 $ mysql -uroot -p<password>
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)
110 Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
112 mysql> grant all on <kohadatabasename>.* to '<kohadatabaseuser>'@'localhost' identified by '<kohadatabaseuserpassword>';
113 Query OK, 0 rows affected (0.00 sec)
115 mysql> flush privileges;
116 Query OK, 0 rows affected (0.00 sec)
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.
123 2.2 Test your SAX Parser and correct where necessary
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:
130 $ misc/sax_parser_print.pl
132 You should see something like:
134 XML::LibXML::SAX::Parser=HASH(0x81fe220)
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.
139 The file is typically located at:
141 /etc/perl/XML/SAX/ParserDetails.ini
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:
146 [XML::LibXML::SAX::Parser]
147 http://xml.org/sax/features/namespaces = 1
149 2.3 Create your Koha system user (if you haven't created one already)
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.
155 3. Run the Koha installer
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:
167 Example (for standard install):
168 $ export KOHA_CONF=/etc/koha/koha-conf.xml
169 $ export PERL5LIB=/usr/share/koha/lib
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
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)
179 Add the following lines to /etc/apache2/ports.conf:
184 Run the following commands:
186 $ sudo a2enmod rewrite deflate
188 $ sudo apache2ctl restart
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/).
196 5. Run the Web Installer, populate the database, initial configuration of settings
198 Point your browser to http://<servername>:8080/
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
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
206 you can install the sample data for libraries, patrons, and much more.
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).
212 6. Configure and start Zebra
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).
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.
222 Option 1: run the Zebra processes from the command line (manual indexing):
224 6.1.1 Zebra Search Server
226 This process send responses to search requests sent by Koha or
227 Z39.50/SRU/SRW clients.
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)
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
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.
244 $ sudo -u <kohauser> misc/migration_tools/rebuild_zebra.pl -z -b -a
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).
249 Option 2: run the Zebra process as a daemon (automatic indexing):
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.
255 6.2.1 Zebra Search Server
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
261 $ sudo <script_dir>/koha-zebra-ctl.sh start
262 (Note: <script_dir> is /usr/share/koha/bin/ by default in a standard install)
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).
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).
273 Edit the crontab for the koha user by running
274 $ sudo -u <kohauser> crontab -e
276 For Zebra indexing, you are looking for the example that begins with
278 # ZEBRA INDEX UPDATES with -z option, incremental index updates throughout the day
279 # for both authorities and bibs
281 It may be easiest to copy/paste the example into your own crontab and modify as necessary.
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):
290 $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml
291 (note: use the correct path to your koha-conf.xml)
295 Bibliographic data in MARC21 format
297 $ misc/migration_tools/bulkmarcimport.pl -file /path/to/marc.iso2709
299 Authority data in MARC21 format
301 $ misc/migration_tools/bulkmarcimport.pl -a -file /path/to/auth.iso2709
304 $ misc/migration_tools/rebuild_zebra.pl -b -w
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).
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).
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.
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
325 If you are upgrading from a previous installation of Koha 3.x, you can
328 ./koha_perl_deps.pl -u -m # to identify new Perl dependencies
330 Install any missing modules
331 IMPORTANT: Koha 3.6.x uses Template::Toolkit, this must be installed
332 before the webinstaller can run
334 sudo apt-get install libtemplate-perl
336 perl Makefile.PL --prev-install-log /path/to/koha-install-log
341 Koha 3.4.x or later no longer stores items in biblio records so
342 if you upgrading from an old version as part of the
343 upgrade you will need to do the following two steps, they can take a
344 long time (several hours) to complete for large databases
346 misc/maintenance/remove_items_from_biblioitems.pl --run
347 misc/migration_tools/rebuild_zebra.pl -b -r
349 Uninstall Instructions
350 =============================
352 $ sudo a2dissite koha
353 $ sudo rm /etc/apache2/sites-available/koha
354 $ sudo apache2ctl restart
356 $ sudo update-rc.d koha-zebra-daemon remove
357 $ sudo rm /etc/init.d/koha-zebra-daemon
359 2) Remove Database and Indexes
362 $ mysql -u<kohauser> -p<kohapassword>
363 > drop database koha;
366 $ zebraidx -c <prefix>/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
367 $ zebraidx -c <prefix>/etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
369 3) Remove Koha Install Directories and Configuration Files
370 Don't forget about any crontab entries
372 Tested on the following operating environments
373 ==============================================
378 =====================
379 This file is part of Koha
381 Koha is free software; you can redistribute it and/or modify it under the
382 terms of the GNU General Public License as published by the Free Software
383 Foundation; either version 2 of the License, or (at your option) any later
386 Koha is distributed in the hope that it will be useful, but WITHOUT ANY
387 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
388 A PARTICULAR PURPOSE. See the GNU General Public License for more details.
389 You should have received a copy of the GNU General Public License along with
390 Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
391 Suite 330, Boston, MA 02111-1307 USA