README.debian

   1 =============================
   2 Installation Guide for Installing Koha on Debian Etch with MySQL 5
   3 =============================
   4
   5 Copyright (C) 2007, LibLime
   6
   7 Maintainer: Joshua Ferraro (jmf AT liblime DOT com)
   8 Feedback/bug reports: jmf AT liblime DOT com
   9 This document last modified: 22 December 2007
  10
  11 Installation Instructions
  12 =============================
  13
  14 All commands can be performed as a system user with sudo privileges,
  15 as indicated or by running the command directly as root.
  16
  17 Your locale should be set to UTF-8, as should Apache2 and MySQL 5.
  18 This step is VERY IMPORTANT for a UNICODE compliant system. Please
  19 read over the following document carefully:
  20
  21 http://wiki.koha.org/doku.php?id=encodingscratchpad
  22
  23 1. Prepare System and Install Dependencies
  24
  25 1.1 Install Debian Etch via Businesscard CD
  26
  27 See http://www.debian.org/devel/debian-installer/
  28
  29 1.2 Set up apt sources for Git, Yaz and Zebra packages
  30
  31 Edit your /etc/apt/sources.list file and add the following:
  32
  33     # Index Data
  34     deb http://ftp.indexdata.dk/debian etch main
  35     deb-src http://ftp.indexdata.dk/debian etch main
  36
  37     # Backports
  38     deb http://www.backports.org/debian etch-backports main contrib non-free
  39
  40 Backports packages are signed with a key you can install as follows:
  41
  42     $ sudo apt-get install debian-backports-keyring
  43
  44 The Index Data packages are signed with a key you can install as follows:
  45
  46     $ wget http://ftp.indexdata.dk/debian/indexdata.asc
  47     $ sudo apt-key add indexdata.asc
  48
  49 Run the following command to update your system:
  50
  51     $ sudo apt-get update
  52     $ sudo apt-get -t etch-backports install git-core git-email
  53     $ sudo apt-get install yaz idzebra-2.0 idzebra-2.0-doc
  54
  55 1.3 Download Koha via Git
  56
  57     $ git clone git://git.koha.org/pub/scm/koha.git kohaclone
  58     $ cd kohaclone
  59     $ git checkout -b myinstall origin
  60
  61 Note: for more information about Git, please see the Koha Git Usage Guide:
  62
  63         http://wiki.koha.org/doku.php?id=en:development:git_usage
  64
  65 1.4 Install additional Debian dependencies
  66
  67 IMPORTANT:  You should only use CPAN for Perl dependencies which are NOT available from the package maintainer.
  68             You have been warned!
  69
  70 Using the debian.packages file included in the Koha source tree,
  71 run the following:
  72
  73     $ sudo dpkg --set-selections < install_misc/debian.packages
  74
  75 Now start dselect:
  76
  77     $ sudo dselect
  78
  79 Choose [I]nstall and accept packages to be installed (hit return)
  80
  81 (may take a while)
  82
  83 Choose [C]onfigure, [R]emove and [Q]uit until dselect has completed.
  84
  85 1.5 Install Perl dependencies that aren't packaged into Debian Etch
  86 sources
  87
  88 Run the following command:
  89
  90     $ sudo cpan MARC::Record Class::Accessor MARC::Charset MARC::File::XML \
  91                 Net::Z3950::ZOOM HTML::Template::Pro MARC::Crosswalk::DublinCore \
  92                 PDF::Reuse PDF::Reuse::Barcode Data::ICal GD::Barcode::UPCE \
  93                 XML::RSS Algorithm::CheckDigits::M43_001 Biblio::EndnoteStyle POE Schedule::At
  94
  95 There is a known but benign error in the test case for Barcode::Code128,
  96 which is required by PDF::Reuse::Barcode.  If this module is not installed,
  97 you can do a forced installation of Barcode::Code128.
  98
  99 Note: you may need to run CPAN initialization if you've not run cpan
 100 before:
 101
 102     /etc/perl/CPAN/Config.pm initialized.
 103
 104     CPAN is the world-wide archive of perl resources. It consists of about
 105     100 sites that all replicate the same contents all around the globe.
 106     Many countries have at least one CPAN site already. The resources
 107     found on CPAN are easily accessible with the CPAN.pm module. If you
 108     want to use CPAN.pm, you have to configure it properly.
 109
 110     If you do not want to enter a dialog now, you can answer 'no' to this
 111     question and I'll try to autoconfigure. (Note: you can revisit this
 112     dialog anytime later by typing 'o conf init' at the cpan prompt.)
 113
 114     Are you ready for manual configuration? [yes]
 115
 116 When the configuration is completed CPAN will install the Perl modules.
 117
 118 2. Configuration of dependencies
 119
 120 2.1 Update root MySQL password (if dselect didn't do it for you already)
 121
 122     $ sudo mysqladmin password <password>
 123
 124 2.2 Create the Koha database
 125
 126     $ mysqladmin -uroot -p<password> create database <kohadatabasename>
 127     $ mysql -uroot -p<password>
 128
 129     Create the database and user with associated privileges:
 130
 131     Welcome to the MySQL monitor.  Commands end with ; or \g.
 132     Your MySQL connection id is 22
 133     Server version: 5.0.32-Debian_7etch3-log Debian etch distribution
 134
 135     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
 136
 137     mysql> create database <kohadatabasename>;
 138     Query OK, 1 row affected (0.00 sec)
 139
 140     mysql> grant all on <kohadatabasename>.* to '<kohadatabaseuser>'@'localhost' identified by '<kohadatabaseuserpassword>';
 141     Query OK, 0 rows affected (0.00 sec)
 142
 143     mysql> flush privileges;
 144     Query OK, 0 rows affected (0.00 sec)
 145
 146     mysql> quit
 147
 148 2.3 Create test database in order to install DBD::mysql
 149
 150 In order to handle UTF-8 correctly, Koha requires at least version 4.004
 151 of the DBD::mysql Perl module.  However, Debian Etch has a stable package
 152 only for version 3.0008, so it is necessary to install the module  from CPAN.
 153 Because of DBD::mysql's test suite, it is necessary to temporarily create a
 154 test database and user:
 155
 156     $ mysql -uroot -p<password>
 157
 158     Create the database and user with associated privileges:
 159
 160     Welcome to the MySQL monitor.  Commands end with ; or \g.
 161     Your MySQL connection id is 22
 162     Server version: 5.0.32-Debian_7etch3-log Debian etch distribution
 163
 164     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
 165
 166     mysql> create database test;
 167     Query OK, 1 row affected (0.00 sec)
 168
 169     mysql> grant all on test.* to 'test'@'localhost' identified by 'test';
 170     Query OK, 0 rows affected (0.00 sec)
 171     (test database, user, and password can be different if need be)
 172
 173     mysql> flush privileges;
 174     Query OK, 0 rows affected (0.00 sec)
 175
 176     mysql> quit
 177
 178 Next install DBD::mysql:
 179
 180     $ sudo cpan
 181
 182     cpan> o conf makepl_arg
 183     (get current value of this CPAN parameter)
 184
 185     cpan> o conf makepl_arg "--testdb=test --testuser=test --testpass=test"
 186
 187     cpan> install DBD::mysql
 188
 189     cpan> o conf makepl_arg ''
 190     (clear this setting to not interface with future CPAN installs).
 191
 192
 193 Finally, remove the test database:
 194
 195     $ mysql -uroot -p<password>
 196
 197     mysql> drop database test;
 198     Query OK, 1 row affected (0.00 sec)
 199
 200     mysql> exit
 201     Bye
 202
 203 3. Run the Koha installer
 204
 205     $ perl Makefile.PL
 206     ( answer questions )
 207     $ make
 208     $ make test
 209     $ sudo make install
 210
 211 4. Configure and start Apache
 212     $ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha
 213     (note that the path to koha-httpd.conf may be different depending on your
 214     installation choices)
 215
 216 Add the following lines to /etc/apache2/ports.conf:
 217
 218     Listen 80
 219     Listen 8080
 220
 221 Run the following commands:
 222
 223     $ sudo a2enmod rewrite
 224     $ sudo a2ensite koha
 225     $ sudo apache2ctl restart
 226
 227 5. Configure and start Zebra
 228
 229 Note: it's recommended that you daemonize the Zebra process and add it to your
 230 startup profile. For a non-production test/development installation, running
 231 Zebra from the command line can be useful. Pick from the two available options
 232 below, or roll your own :-)
 233
 234 Note: it's also recommended that you create a Koha system user, which you will
 235 have specified during the install process. Alternatively, Zebra can be
 236 configured to run as the root user.
 237
 238 Option 1: run the Zebra processes from the command line:
 239
 240     Zebra Server:
 241     $ sudo -u ${KOHA_USER} zebrasrv -f /etc/koha/koha-conf.xml
 242     (note that the path to koha-conf.xml may be different depending on your
 243     installation choices)
 244
 245     Note: the user you run Zebra as will be the only user with write permission
 246     on the Zebra index; in development mode, you may wish to use your system
 247     user.
 248
 249     Zebraqueue Daemon:
 250     $ sudo -u ${KOHA_USER} misc/bin/zebraqueue_daemon.pl
 251
 252     Note: if you are running in this mode, you may wish to defer starting the
 253     zebraqueue until you've run the web installer (see below).
 254
 255 Option 2: run the Zebra processes as daemons, and add to startup process:
 256
 257 Note that references to $SCRIPT_DIR refer to the directory where
 258 Koha's command-line scripts are installed, e.g., /usr/share/koha/bin.
 259
 260     Zebra Server:
 261     $ sudo ln -s ${SCRIPT_DIR}/koha-zebra-ctl.sh  /etc/init.d/koha-zebra-daemon
 262     (Note: ${SCRIPT_DIR} is /usr/share/koha/bin/ by default in a standard install)
 263     $ sudo update-rc.d koha-zebra-daemon defaults
 264     ( Note: see man chkconfig(8) on other distros )
 265
 266     $ sudo ${SCRIPT_DIR}/koha-zebra-ctl.sh start
 267
 268     Zebraqueue Daemon:
 269     $ sudo ln -s ${SCRIPT_DIR}/koha-zebraqueue-ctl.sh  /etc/init.d/koha-zebraqueue-daemon
 270     $ sudo update-rc.d koha-zebraqueue-daemon defaults
 271     ( Note: see man chkconfig(8) on other distros )
 272
 273     $ sudo ${SCRIPT_DIR}/koha-zebraqueue-ctl.sh start
 274
 275 6. Run the Web Installer, populate the database, initial configuration of settings
 276
 277     Point your browser to http://<servername>:8080/
 278
 279     It should redirect you to the Web installer where you can continue the setup.
 280
 281 Uninstall Instructions
 282 =============================
 283 1) Stop Services:
 284    $ sudo a2dissite koha
 285    $ sudo rm /etc/apache2/sites-available/koha
 286    $ sudo apache2ctl restart
 287
 288    $ sudo update-rc.d koha-zebra-daemon remove
 289    $ sudo update-rc.d koha-zebraqueue-daemon remove
 290    $ sudo rm /etc/init.d/koha-zebra-daemon
 291    $ sudo rm /etc/init.d/koha-zebraqueue-daemon
 292
 293 2) Remove Koha Database
 294
 295    # MySQL
 296    $ mysql -u<kohauser> -p<kohapassword>
 297    > drop database koha;
 298
 299    # Zebra Indexes
 300    $ zebraidx -c <prefix>/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
 301    $ zebraidx -c <prefix>/etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
 302
 303 3) Remove Koha Install Directories
 304
 305 Tested on the following operating environments
 306 ==============================================
 307 - Debian Etch 4.0
 308
 309 Installer Bug reports
 310 =====================
 311 Please send any installer bug reports to jmf AT liblime DOT com
 312
 313 Other Notes
 314 =====================
 315 This file is part of Koha
 316
 317 Koha is free software; you can redistribute it and/or modify it under the
 318 terms of the GNU General Public License as published by the Free Software
 319 Foundation; either version 2 of the License, or (at your option) any later
 320 version.
 321
 322 Koha is distributed in the hope that it will be useful, but WITHOUT ANY
 323 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
 324 A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 325 You should have received a copy of the GNU General Public License along with
 326 Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
 327 Suite 330, Boston, MA  02111-1307 USA