INSTALL

   1 Koha - Requirements and quick-start installation guide
   2
   3 INSTALL document included with [Koha]
   4
   5 For information on how to install Koha without requiring multiple virtual servers - See KohaAllInOne.
   6 For additional information on how your Configuration files should look see the Hints file.
   7
   8 Important....
   9 To successfully use Koha you need some additional software:
  10
  11 A webserver (It was built to work with Apache, but there is no reason it shouldnt work with any other webserver).
  12 Mysql (You could intead use postgres, or another sql based database)
  13 Perl (mod_perl isnt needed, tho koha should work with mod_perl but this hasnt been tested yet).
  14
  15 Perl Modules:
  16
  17 Date::Manip
  18 DBI
  19 Set::Scalar
  20 DBD::mysql (or whatever database system you use)
  21 AuthenDBI (if you want to use Database based authentication)
  22 CDK (for the telnet interface not nessecary if you plan to use the web based circulation module) also requires installation of the C CDK libraries http://www.vexus.ca/CDK.html ( CDKModuleHasProblems )
  23 File::Spec (Required for HTML::Template)
  24 HTML::Template
  25
  26 --------------------------------------------------------------------------------
  27
  28
  29 Quick-start Installation Guide
  30 (Assumes the Use of MySQL and Apache)
  31
  32 1. Create a new mysql database called for example Koha
  33 From command line: mysqladmin -uroot -ppassword create Koha
  34 There is a databse installation shell script included with the Koha tarball.
  35
  36 2. Set up a koha user and password in mysql
  37 Log in to mysql: mysql -uroot -ppassword
  38
  39 To create a user called "koha" who has full administrative rights to the "Koha" database when autheicting from "localhost", enter the following on mysql command line:
  40
  41 grant all privileges on Koha.* to koha@localhost identified by 'kohapassword';
  42
  43 Press ENTER, and if you see no errors then enter \q to quit mysql.
  44
  45
  46 3. Use the mysql script to create the tables
  47 mysql -uusername -ppassword Koha < koha.mysql
  48
  49 3.1 Update your database tables
  50 perl updatedatabase -I /pathtoC4
  51
  52 4. Edit koha.conf
  53         This file resides on the web server and tells the Koha scripts
  54    how to access the database, and where scripts and documents are
  55    installed. It is of the form:
  56         # This is a comment
  57         variable = value
  58         foo = bar   # This is also a comment
  59
  60         The following variables are currently supported:
  61    database
  62         Name of the Koha database that you created in step 1 above.
  63    user
  64    pass
  65         Name and password of the Koha database user that you creted in
  66         step 2
  67    includes
  68         Directory where you plan to install the include files (*.inc)
  69         in step 6.
  70
  71         The "database", "user", and "pass" settings are required.
  72
  73 5. Install koha.conf
  74         By default, Koha looks for its configuration file in
  75    /etc/koha.conf, though you may override this by setting the
  76    $KOHA_CONF environment variable to the path to a different file.
  77         If you are using Apache 1.1 or later, with virtual hosts, you
  78    can use the SetEnv directive to use a different configuration file
  79    for each virtual host.
  80
  81         Security note: /etc/koha.conf must be readable by the UID
  82    under which the web server is running, and any other users running
  83    Koha-related scripts or programs. It need not be writable.
  84
  85 6. Create directories for scripts and html documents.
  86 Here you need to decide where your scripts and html are going to live.
  87 And edit C4/Output.pm to reflect that.
  88 Set $path= where your includes live,
  89 for example: $path="/usr/local/www/koha/htdocs/includes";
  90
  91 You do not need to do that if you have already entered the includes path in koha.conf (see example above)
  92
  93 Next copy the C4 directory (in scripts/) to somewhere in your perl path
  94 eg /usr/local/lib/site_perl/i386-linux/
  95
  96 If you do not have sufficient access to copy the files to the default perl folder (maybe you are using your ISPs hosting server) then you can copy the modules to any other location and add a line to apache.conf like:
  97
  98 SetEnv PERL5LIB "/usr/local/www/koha/modules"
  99
 100 Copy the C4 directory into the modules folder (see detailed example in KohaHints)
 101
 102
 103 7. Set up your Online Public Access Catalogue (OPAC)
 104
 105 Set up a webspace for the OPAC: For example: You might make /usr/local/www/opac ... and set a virtual host in apache to use that dir
 106 In your opac dir make a dir called htdocs, and copy everything in opac-html/ to it.
 107 Again in your opac dir make a dir called cgi-bin and copy all the files in scripts/ that have a .pl extension to it, eg copy scripts/*.pl /usr/local/www/opac/cgi-bin/koha/
 108 Your virtual host should be set up to use these dirs, some thing like this:
 109
 110
 111    <VirtualHost opac.your.site>
 112    ServerAdmin webmaster@your.site
 113    DocumentRoot /usr/local/www/opac/htdocs
 114    ServerName opac.your.site
 115    ErrorLog logs/opac-error_log
 116    TransferLog logs/opac-access_log
 117
 118    SetEnv KOHA_CONF /usr/local/etc/koha.conf
 119    </VirtualHost>
 120
 121
 122 When finished, restart apache and point your browser at opac.your.site and it should be all go (of course - if you dont have any data in the database there wont be much to see!)
 123
 124 Find supplementary information and config examples in KohaHints
 125
 126 8. Set up the intranet/librarian interface
 127
 128 Create new directories and additional httpd.conf changes to Set up another webspace. Lets call it koha.
 129 For example:
 130
 131 In the dir you have just created make an htdocs dir and a cgi-bin dir
 132 Copy everything in intranet-html/ to the htdocs dir
 133 Copy all the .pl files in scripts/ to the cgi-bin/koha dir
 134 Make sure your virtual host is set up to use these dirs
 135 Restart apache point your browser at koha.your.site and it should work
 136
 137
 138 9. Configure SECURITY for the Librarians/Intranet Interface
 139 If you are using AuthenDBI to do your authentication, you will need to add some users to the users table in the koha database. And edit your apache conf file to use AuthenDBI on the intranet site.
 140
 141 Otherwise, set up htaccess files in both koha/htdocs/ and koha/cgi-bin You can use general .htaccess based security. It is important though to password protect the librarians interface because from it you can delete and add items, remove borrowers fines and generally case havoc.
 142
 143
 144 10. Set up Issues, Returns and Telnet interface.
 145 Since we have already copied the files in scripts/C4 into somewhere in our perl source tree
 146
 147 We just need to now copy the scripts from scripts/telnet/ into somewhere in the executable path, eg /usr/local/bin
 148
 149 Then its done: type circ and your away, ready to issue and return.
 150
 151 In release 1.1.0 on there is now a webbased circulation module, So issues and returns can be done from there, or from circ.
 152
 153
 154 You will find some Koha config examples in KohaHints
 155
 156
 157 Check out KohaMiniFAQ for general, supplementary information.