INSTALL.ubuntu

   1 =============================
   2 Installation Guide for Installing Koha on Ubuntu Jaunty (9.04) with MySQL 5
   3 =============================
   4
   5 Copyright (C) 2007, 2008 LibLime (http://liblime.com)
   6
   7 Original author: Joshua Ferraro (jmf AT liblime DOT com)
   8 Modified for Ubuntu by: Chris Nighswonger (cnighswonger AT foundations DOT edu)
   9
  10 Feedback/bug reports: Koha Developer's List:
  11 http://lists.koha.org/mailman/listinfo/koha-devel
  12
  13 This document last modified: 22 June 2009
  14
  15 Installation Instructions
  16 =============================
  17
  18 All commands can be performed as a system user with sudo privileges,
  19 as indicated or by running the command directly as root.
  20
  21 1. Prepare System and Install Dependencies
  22
  23 1.1 Install Ubuntu Jaunty via CD
  24
  25 See http://www.ubuntu.com/getubuntu/download
  26
  27 1.2 Set up your locale
  28
  29 Your locale should be set to UTF-8, as should Apache2 and MySQL 5.
  30 This step is VERY IMPORTANT for a UNICODE compliant system. Please
  31 read over the following document carefully:
  32
  33 http://wiki.koha.org/doku.php?id=encodingscratchpad
  34
  35 You can verify your system locale by typing the following command:
  36
  37     $ locale
  38
  39 IMPORTANT:  You _MUST_ follow all the steps outlined there for
  40             Apache2, MySQL 5, etc. BEFORE you install Koha.
  41
  42 1.3 Install the Yaz and Zebra packages
  43
  44 Run the following command to update your system:
  45
  46     $ sudo apt-get update
  47     $ sudo apt-get install yaz idzebra-2.0 idzebra-2.0-doc
  48
  49 1.4 Get Koha
  50
  51 1.4.1 Option A: Download Koha via Git (optional)
  52
  53     $ sudo apt-get install git-core git-email
  54     $ git clone git://git.koha.org/pub/scm/koha.git kohaclone
  55     $ cd kohaclone
  56     $ git checkout -b myinstall origin
  57
  58 Note: for more information about Git, please see the Koha Git Usage Guide:
  59
  60     http://wiki.koha.org/doku.php?id=en:development:git_usage
  61
  62 1.4.2 Option B: Download Koha from http://download.koha.org
  63
  64     $ wget http://download.koha.org/koha-3.00.02.tar.gz
  65     ( Note: use the latest stable version)
  66
  67 1.5 Install additional Ubuntu dependencies
  68
  69 IMPORTANT:  You should only use CPAN for Perl dependencies which are NOT
  70             available from the package maintainer. You have been warned!
  71
  72 Using the ubuntu.packages file included in the Koha source tree,
  73 run the following:
  74
  75     $ sudo dpkg --set-selections < install_misc/ubuntu.packages
  76
  77 Now start dselect (you may need to 'sudo apt-get install dselect'):
  78
  79     $ sudo dselect
  80
  81 Choose [I]nstall and accept packages to be installed (hit return)
  82
  83 (may take a while)
  84
  85 Choose [C]onfigure, [R]emove and [Q]uit until dselect has completed.
  86
  87 1.6 Install Perl dependencies that aren't packaged into Ubuntu Jaunty
  88 sources
  89
  90 Run the following command:
  91
  92     $ sudo cpan MARC::Crosswalk::DublinCore GD GD::Barcode::UPCE Email::Date \
  93                 HTML::Scrubber Algorithm::CheckDigits::M43_001 Biblio::EndnoteStyle \
  94                 Locale::Currency::Format
  95
  96 Note: you may need to run CPAN initialization if you've not run cpan
  97 before:
  98
  99     /etc/perl/CPAN/Config.pm initialized.
 100
 101     CPAN is the world-wide archive of perl resources. It consists of about
 102     100 sites that all replicate the same contents all around the globe.
 103     Many countries have at least one CPAN site already. The resources
 104     found on CPAN are easily accessible with the CPAN.pm module. If you
 105     want to use CPAN.pm, you have to configure it properly.
 106
 107     If you do not want to enter a dialog now, you can answer 'no' to this
 108     question and I'll try to autoconfigure. (Note: you can revisit this
 109     dialog anytime later by typing 'o conf init' at the cpan prompt.)
 110
 111     Are you ready for manual configuration? [yes]
 112
 113 When the configuration is completed CPAN will install the Perl modules.
 114
 115 2. Configuration of dependencies
 116
 117 2.1 Update root MySQL password (if dselect didn't do it for you already)
 118
 119     $ sudo mysqladmin password <password>
 120
 121 2.2 Create the Koha database
 122
 123     Create the database and user with associated privileges:
 124
 125     $ mysqladmin -uroot -p<password> create <kohadatabasename>
 126     $ mysql -uroot -p<password>
 127
 128     Welcome to the MySQL monitor.  Commands end with ; or \g.
 129     Your MySQL connection id is 22
 130     Server version: 5.0.32-Debian_7etch3-log Debian etch distribution
 131
 132     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
 133
 134     mysql> grant all on <kohadatabasename>.* to '<kohadatabaseuser>'@'localhost' identified by '<kohadatabaseuserpassword>';
 135     Query OK, 0 rows affected (0.00 sec)
 136
 137     mysql> flush privileges;
 138     Query OK, 0 rows affected (0.00 sec)
 139
 140     mysql> quit
 141
 142 2.3 Test your SAX Parser and correct where necessary
 143
 144     You must be sure you're using the XML::LibXML SAX parser, not Expat or PurePerl, both of which have outstanding bugs with pre-composed characters. You can test your SAX parser by running:
 145
 146     $ cd koha
 147     $ misc/sax_parser_print.pl
 148
 149     You should see something like::
 150
 151     XML::LibXML::SAX::Parser=HASH(0x81fe220)
 152
 153     If you're using PurePerl or Expat, you'll need to edit your
 154     ini file, typically located at:
 155
 156     /etc/perl/XML/SAX/ParserDetails.ini
 157
 158 2.4 Install DBD::mysql Perl module
 159
 160 In order to handle UTF-8 correctly, Koha requires at least version 4.004
 161 of the DBD::mysql Perl module. However, Debian Etch has a stable package
 162 only for version 3.0008, so it is necessary to install the module  from CPAN.
 163 DBD::mysql's test suite needs to use a MySQL 'test' DB which doesn't exist
 164 anymore. So there are two options to install DBD::mysql:
 165
 166   (1) install without test suite,
 167   (2) install with test suite requiring a test MySQL DB creation.
 168
 169 2.4.1 Install without test suite
 170
 171 Force install DBD::mysql:
 172
 173     $ sudo cpan
 174     cpan> force install DBD::mysql
 175
 176 2.4.2 Create test database in order to install DBD::mysql
 177
 178 Because of DBD::mysql's test suite, it is necessary to temporarily create a
 179 test database and user:
 180
 181     $ mysql -uroot -p<password>
 182
 183     Create the database and user with associated privileges:
 184
 185     Welcome to the MySQL monitor.  Commands end with ; or \g.
 186     Your MySQL connection id is 22
 187     Server version: 5.0.32-Debian_7etch3-log Debian etch distribution
 188
 189     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
 190
 191     mysql> create database test;
 192     Query OK, 1 row affected (0.00 sec)
 193
 194     mysql> grant all on test.* to 'test'@'localhost' identified by 'test';
 195     Query OK, 0 rows affected (0.00 sec)
 196     (test database, user, and password can be different if need be)
 197
 198     mysql> flush privileges;
 199     Query OK, 0 rows affected (0.00 sec)
 200
 201     mysql> quit
 202
 203 Next install DBD::mysql:
 204
 205     $ sudo cpan
 206
 207     cpan> o conf makepl_arg
 208     (get current value of this CPAN parameter)
 209
 210     cpan> o conf makepl_arg "--testdb=test --testuser=test --testpass=test"
 211
 212     cpan> install DBD::mysql
 213
 214     cpan> o conf makepl_arg ''
 215
 216     OR
 217
 218     cpan> o conf makepl_arg '<old setting>'
 219
 220     (restore this setting so as to not interfere with future CPAN installs).
 221
 222
 223 Finally, remove the test database:
 224
 225     $ mysql -uroot -p<password>
 226
 227     mysql> drop database test;
 228     Query OK, 1 row affected (0.00 sec)
 229
 230     mysql> exit
 231     Bye
 232
 233 3. Run the Koha installer
 234
 235     $ perl Makefile.PL
 236     ( answer questions )
 237     $ make
 238     $ make test
 239     $ sudo make install
 240
 241 4. Configure and start Apache
 242     $ sudo ln -s /etc/koha/koha-httpd.conf /etc/apache2/sites-available/koha
 243     (note that the path to koha-httpd.conf may be different depending on your
 244     installation choices)
 245
 246 Add the following lines to /etc/apache2/ports.conf:
 247
 248     Listen 80
 249     Listen 8080
 250
 251 If not running named virtual hosts (The default koha installation does not use named virtual hosts.), comment out the following line:
 252
 253     NameVirtualHost *:80
 254
 255 Run the following commands:
 256
 257     $ sudo a2enmod rewrite
 258     $ sudo a2ensite koha
 259     $ sudo apache2ctl restart
 260
 261 Note: you may still see the usual Apache default site if your VirtualHost
 262 configuration isn't correct.  The command "sudo a2dissite default" may be a
 263 quick fix, but may have side-effects.  See the Apache HTTPD manual section on
 264 virtual hosts for full instructions.
 265
 266 5. Configure and start Zebra
 267
 268 Note: it's recommended that you daemonize the Zebra process and add it to your
 269 startup profile. For a non-production test/development installation, running
 270 Zebra from the command line can be useful. Pick from the two available options
 271 below, or roll your own :-)
 272
 273 Note: it's also recommended that you create a Koha system user, which you will
 274 have specified during the install process. Alternatively, Zebra can be
 275 configured to run as the root user.
 276
 277 To add a user do:
 278
 279         $ sudo adduser koha
 280
 281
 282 Option 1: run the Zebra processes from the command line:
 283
 284     Zebra Server:
 285     $ sudo -u ${KOHA_USER} zebrasrv -f /etc/koha/koha-conf.xml
 286     (note that the path to koha-conf.xml may be different depending on your
 287     installation choices)
 288
 289     Note: the user you run Zebra as will be the only user with write permission
 290     on the Zebra index; in development mode, you may wish to use your system
 291     user.
 292
 293     Zebraqueue Daemon:
 294     $ sudo -u ${KOHA_USER} misc/bin/zebraqueue_daemon.pl
 295
 296     Note: if you are running in this mode, you may wish to defer starting the
 297     zebraqueue until you've run the web installer (see below).
 298
 299 Option 2: run the Zebra processes as daemons, and add to startup process:
 300
 301 Note that references to $SCRIPT_DIR refer to the directory where
 302 Koha's command-line scripts are installed, e.g., /usr/share/koha/bin.
 303
 304     Zebra Server:
 305     $ sudo ln -s ${SCRIPT_DIR}/koha-zebra-ctl.sh  /etc/init.d/koha-zebra-daemon
 306     (Note: ${SCRIPT_DIR} is /usr/share/koha/bin/ by default in a standard install)
 307     $ sudo update-rc.d koha-zebra-daemon defaults
 308     ( Note: see man chkconfig(8) on other distros )
 309
 310     $ sudo ${SCRIPT_DIR}/koha-zebra-ctl.sh start
 311
 312     Zebraqueue Daemon:
 313     $ sudo ln -s ${SCRIPT_DIR}/koha-zebraqueue-ctl.sh  /etc/init.d/koha-zebraqueue-daemon
 314     $ sudo update-rc.d koha-zebraqueue-daemon defaults
 315     ( Note: see man chkconfig(8) on other distros )
 316
 317     $ sudo ${SCRIPT_DIR}/koha-zebraqueue-ctl.sh start
 318
 319 6. Run the Web Installer, populate the database, initial configuration of settings
 320
 321     Point your browser to http://<servername>:8080/
 322
 323     It should redirect you to the Web Installer where you can continue the setup.
 324     You can install the sample data for libraries, patrons, etc. via the Web Installer
 325
 326 7. What next?
 327
 328     Once the installer has completed, you can import and index MARC records from the
 329     command line thusly (Note: you can also use the 'Stage MARC records for import' from
 330     the Tools area of Koha's Staff Client to import a batch of MARC records):
 331
 332     $ export KOHA_CONF=/usr/share/koha/etc/koha-conf.xml
 333       (note: use the correct path to your koha-conf.xml)
 334
 335 7.1 Import:
 336     Bibliographic data in MARC21 format
 337     $ misc/migration-tools/bulkmarcimport.pl -file /path/to/marc.iso2709
 338     Authority data in MARC21 format
 339         $ misc/migration-tools/bulkauthimport.pl -file /path/to/auth.iso2709
 340
 341 7.2 Fast Index:
 342     $ misc/migration-tools/rebuild_zebra.pl -b -w
 343
 344     Once the indexing has completed, you will be able to search for records in your
 345     system. NOTE: if you don't run the Fast Index utility, and you have the index
 346         updates scheduled as per 7.3 the indexing process will happen in the background,
 347         but it will be orders of magnitude slower.
 348
 349 7.3 Schedule regular index updates
 350     run rebuild_zebra.pl -b -a -z as a regular cron job, check misc/cronjobs/crontab.example
 351         for usage examples
 352
 353 7.4 To enable public Z39.50/SRU servers, you'll need to edit your koha-conf.xml and
 354     change the <listen> options to listen on a TCP port; then restart the zebra daemon.
 355
 356 UPGRADE
 357 =======
 358 If you are upgrading from a previous installation of Koha 3, you can
 359 use the following:
 360
 361  perl Makefile.PL --prev-install-log /path/to/koha-install-log
 362  make
 363  make test
 364  sudo make upgrade
 365
 366 Uninstall Instructions
 367 =============================
 368 1) Stop Services:
 369    $ sudo a2dissite koha
 370    $ sudo rm /etc/apache2/sites-available/koha
 371    $ sudo apache2ctl restart
 372
 373    $ sudo update-rc.d koha-zebra-daemon remove
 374    $ sudo rm /etc/init.d/koha-zebra-daemon
 375
 376 2) Remove Database and Indexes
 377
 378    # MySQL
 379    $ mysql -u<kohauser> -p<kohapassword>
 380    > drop database koha;
 381
 382    # Zebra Indexes
 383    $ zebraidx -c <prefix>/etc/zebradb/zebra-biblios.cfg -g iso2709 -d biblios init
 384    $ zebraidx -c <prefix>/etc/zebradb/zebra-authorities.cfg -g iso2709 -d authorities init
 385
 386 3) Remove Koha Install Directories and Configuration Files
 387    Don't forget about any crontab entries
 388
 389 Tested on the following operating environments
 390 ==============================================
 391 - Ubuntu Jaunty Jackalope 9.04
 392
 393 Installer Bug reports
 394 =====================
 395 Please log any installer bug reports at http://bugs.koha.org
 396
 397 Other Notes
 398 =====================
 399 This file is part of Koha
 400
 401 Koha is free software; you can redistribute it and/or modify it under the
 402 terms of the GNU General Public License as published by the Free Software
 403 Foundation; either version 2 of the License, or (at your option) any later
 404 version.
 405
 406 Koha is distributed in the hope that it will be useful, but WITHOUT ANY
 407 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
 408 A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 409 You should have received a copy of the GNU General Public License along
 410 with Koha; if not, write to the Free Software Foundation, Inc.,
 411 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.