"What is written without effort is, in general, read without pleasure."
-Samuel Johnson
The usual pattern for a Koha installation is the setup of a dedicated server in the library to support the installation of a server grade operating system and the necessary support software. Koha was originally designed to run with Apache running on Linux. Most sites have continued this trend. Koha should run with little or no adjustment necessary on most versions of Unix. Similarly, there are no Apache specific areas in the code, however we have little feedback on how the application will run with other HTTP daemons. Any feedback is most appreciated.
It is possible to run Koha on Microsoft's Windows server platform with appropriate ports of support tools. To prevent confusion, a separate section will eventually cover the steps necessary to adjust Koha for Windows. A mail list devoted to windows related koha issues has been started at:
NB: All the Koha system administrators are firm believers in backing up the database on a regular schedule, especially before upgrades to existing Koha installations.
The preferred method of Koha installation for anyone running a Unix operating system and a machine explicity for Koha is to run the installation script:
perl installer.pl |
which can be found with the tarball.
Using the Installer
The installer.pl utility will:
Check for perl modules
Prompt for an installation directory for the OPAC files. (Default value is /usr/local/koha/opac/.)
Prompt for an installation directory for the Intranet files. (Default value is /usr/local/koha/intranet/.)
Prompt for an installation directory for koha.conf. (Default value is /etc/koha.conf)
Prompt for a name for Koha's Mysql database. (Default value is Koha.)
Prompt for the hostname where the database is located. (Default is localhost)
Note: Using a database hosted on another server will probably break installer.pl at this point, as it uses mysql client tools (mysql and mysqladmin) for creating and populating the database.
Prompt for a mysql user for Koha to use. (Default is kohaadmin.)
Prompt for a mysqlpassword for the Koha user. (There is no default.)
Prompts for an email address for the Apache Virtual Hosts (Default is webmaster@YOUR.DOM.AIN.)
Prompts for the domain name or ip address of the server. (Default is the installing machine's hostname.)
Prompts for a port for the OPAC virtual host. (Default is port 80.)
Note: Using port 80 for the OPAC interface will "hide" any other web content being served from Apache's default root directory. If the server is serving other web content already, the OPAC interface should be put on a port other than 80. Port 8000 might be a good suggestion.
Prompt for a port for the INTRANET virtual host. (Default is 8080.)
Copies all of the files to their final locations.
Prompts for the MySQL root password.
Creates and Updates the Koha database.
Prompts to install the sample data. (Default is No.)
Note: If you are installing Koha for evaluation purposes, you may install a batch of sample data now. If you are installing Koha with the intention of populating it with your own data, you probably don't want this sample data installed.
If you do install the sample data, the script will prompt the user for a library branch and a printer. Default values are "Main Library", "MAIN" and "Library Printer", "lp".
The install.pl displays a message stating that the INTRANET interface can be reached at http://your.machine.name:8080/ and the OPAC can be reached at http://your.machine.name:80/.
The last prompt is to restart the apache webserver. (Default is No, as this is a tad aggressive!)
Post installation steps for users of installer.pl
The Z39.50 Client requires a separate daemon process to be running to process the queue that is generated through the web page. This daemon is not automatically installed by the Koha installer due to the widely varying configurations for starting up daemons. You should check the documentation for your variant of Unix for more information.
A script is included for starting up this daemon in:
./intranet-cgi/acqui.simple/z3950-daemon-launch.sh |
You will need to edit this script to set the "RunAsUser" variable to the user that your web server runs as, and the KohaDir variable to the location of your acqui.simple directory.
If you so desire, you can follow the standard installation route by following the Step By Step directions...
If you are comfortable with Unix system configuration and installation, it is possible to perform the installation steps manually. This is recommended only in situations where you have difficulties with the installer, or have a need for a custom configuration that is not covered by the options of the installer.
To successfully setup Koha in this configuration, you will need to insure you the necessary components -- the customary selections for these supporting tools are listed in parentheses:
A webserver (Apache).
A SQL based database. (MySQL)
Perl and the associated modules:
Date::Manip
DBI
Set::Scalar
DBD::mysql (or whatever database system you use)
AuthenDBI (if you want to use Database based authentication)
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 (currently, the CDK Module has problems )
Examples of the koha.conf and httpd.conf (for virtual hosts configuration) files and the commands for database creation with various databases can be found in the downloadable Koha tarball and the appendices for this manual.
To install Koha without access to superuser/root/sysadmin level privileges, ask your system administrator to arrange for a user called opac and then set the user in the OPAC virtual host. This will permit all of the cgi scripts to be executed as 'user' opac. The Virtualhost then may suexec to the user installing Koha, and koha.conf can then be written by that user, avoiding the need for the chown command, which is restricted to a superuser. It is then extremely important to set PERL5LIB environment variable to point at the libraries you have installed:
SetEnv PERL5LIB /some/path/to/modules |
Koha is designed to be installed as two separate services - each having a unique web address and folder structure (two virtual web hosts). Both services access a single SQL database which may be hosted on the same server or on a remote server. Following the steps below reconfigure koha (the intranet and opac) to run on a single, non-virual server.
NB: In the examples below, pathto = /usr/local/www
Create new /etc/koha.confdatabase=kohadb hostname=localhost user=kohadbuser pass=xxxxxxxx includes=/pathto/html/koha/includes |
Create a general purpose web site:
/pathto/html
/pathto/cgi-bin
Create koha web installations folders:
/pathto/html/koha/includes
/pathto/html/koha/oadmin
/pathto/html/koha/opac
Create koha cgi-bin folders:
/pathto/cgi-bin/opac
/pathto/cgi-bin/koha
/pathto/cgi-bin/koha/C4
Copy koha distro opac-html\* into /pathto/koha/opac/*
Copy koha distro intranet-html\* into /pathto/koha/oadmin/*
koha distro koha\* into /pathto/cgi-bin/oadmin (including C4 directory and its contents).
Copy member.pl + seach.pl into /pathto/cgi-bin/opac
Move /pathto/koha/opac/images/* into /pathto/images/opac/*
Move /pathto/koha/oadmin/images/* into /pathto/images/oadmin/*
Rename opac *.inc files so that they all have opac-* prefix ie
rename "join-top.inc" to "opac-join-top.inc"
and rename "members-top.inc" to "opac-members-top.inc"
Move ALL includes from koha distro into /pathto/koha/includes [(It is preferable that any new includes for opac should be named using the "opac-" prefix convention (or similar)].
Example excerpts from apache httpd.conf:
ServerName library.example.org ServerPath /usr/local/www DocumentRoot /usr/local/www/html # Alias /images/ "/usr/local/www/html/images/" SetEnv PERL5LIB "/usr/local/www/cgi-bin/koha" <Directory /var/www/html > # This is the root of general purpose website # NO server side includes! AllowOverride None Options -Includes -FollowSymlinks -Indexes Order Deny,Allow Allow From All </Directory> # ======== Use Server Side Includes Here ======= <Directory /usr/local/www/html/koha/opac> AllowOverride None Options +Includes -FollowSymlinks -Indexes AddHandler server-parsed .html </Directory> # <Directory "/usr/local/www/html/koha/oadmin"> # AllowOverride None # # First, you must enable +Includes or +IncludesNoExec # in "Options"... Options +Includes -FollowSymlinks -Indexes # # Allow server-parsed content (SSI) for files AddHandler server-parsed .html # # Optional simple server based authentication.... # Authtype Basic # AuthName Koha-Online-Admin # AuthUserFile /usr/local/www/ok_users/koha-users # AuthGroupFile /usr/local/www/ok_groups/koha-groups # <Limit GET POST PUT DELETE> # require user koha-admin group lib-admins # </Limit> </Directory> </VirtualHost> |
Note: You will also need to change the include files to reflect the new "root" directory -- if you don't do this, everything will work until you click on a section button at the top of a page.