Added two missing required Perl modules.
[wip/koha-chris_n.git] / 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
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 Set the database name to what you have called your database, hostname willprobably stay as localhost (unless you are installing the database on a different machine to the webserver) User and password should be changed to reflect the username and password you have chosen above.
54
55 You can include a line called "includes= " with path to your includes folder instead of entering the path in Output.pm - see example in KohaHints.
56
57
58 5. Copy koha.conf to /etc/
59 The permissions on this config file should also be strict, since they contain the database password. At a minimum, the apache user needs to be able to read it, as well as any other user that runs circ.
60 I would suggest ownership of www-data.libadmins with no access to others.libadmins contain all users that use koha (If you set the owner as www-data u will need to make sure apache is running
61 as www-data)
62
63 6. Create directories for scripts and html documents.
64 Here you need to decide where your scripts and html are going to live.
65 And edit C4/Output.pm to reflect that.
66 Set $path= where your includes live,
67 for example: $path="/usr/local/www/koha/htdocs/includes";
68
69 You do not need to do that if you have already entered the includes path in koha.conf (see example above) 
70
71 Next copy the C4 directory (in scripts/) to somewhere in your perl path
72 eg /usr/local/lib/site_perl/i386-linux/
73
74 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:
75
76 SetEnv? PERL5LIB "/usr/local/www/koha/modules"
77
78 Copy the C4 directory into the modules folder (see detailed example in KohaHints)
79
80
81 7. Set up your Online Public Access Catalogue (OPAC)
82
83 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 
84 In your opac dir make a dir called htdocs, and copy everything in opac-html/ to it. 
85 Again in ur 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/ 
86 Your virtual host should be set up to use these dirs, some thing like this: 
87
88
89    <VirtualHost opac.your.site>                         
90    ServerAdmin webmaster@your.site                            
91    DocumentRoot /usr/local/www/opac/htdocs                     
92    ServerName opac.your.site                      
93    ErrorLog logs/opac-error_log       
94    TransferLog logs/opac-access_log               
95    </VirtualHost>
96
97
98 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!) 
99
100 Find supplementary information and config examples in KohaHints
101
102 8. Set up the intranet/librarian interface
103
104 Create new directories and additional httpd.conf changes to Set up another webspace. Lets call it koha. 
105 For example:
106
107 In the dir you have just created make an htdocs dir and a cgi-bin dir 
108 Copy everything in intranet-html/ to the htdocs dir 
109 Copy all the .pl files in scripts/ to the cgi-bin/koha dir 
110 Make sure ur virtual host is set up to use these dirs 
111 Restart apache point your browser at koha.your.site and it should work 
112
113
114 9. Configure SECURITY for the Librarians/Intranet Interface
115 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.
116
117 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.
118
119
120 10. Set up Issues, Returns and Telnet interface.
121 Since we have already copied the files in scripts/C4 into somewhere in our perl source tree
122
123 We just need to now copy the scripts from scripts/telnet/ into somewhere in the executable path, eg /usr/local/bin
124
125 Then its done: type circ and your away, ready to issue and return.
126
127 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.
128
129
130 You will find some Koha config examples in KohaHints 
131
132
133 Check out KohaMiniFAQ for general, supplementary information.