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