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