INSTALL.debian-lenny

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