Copyright © 2003 - 2005 Rob Weir
This document is related to Koha and is licensed to you under the GNU General Public License version 2 or later (http://www.gnu.org/licenses/gpl.html).
Koha-related documents may be reproduced and distributed in whole or in part, in any medium physical or electronic, as long as this copyright notice is retained on all copies.
You may create a derivative work and distribute it provided that you:
License the derivative work with this same license, or the Linux Documentation Project License (http://www.tldp.org/COPYRIGHT.html). Include a copyright notice and at least a pointer to the license used.
Give due credit to previous authors and major contributors.
Commercial redistribution is allowed and encouraged; however, the author would like to be notified of any such distributions.
No liability for the contents of this document can be accepted. Use the concepts, examples and information at your own risk. There may be errors and inaccuracies that could be damaging to your system. Although this is highly unlikely, proceed with caution; the author(s) do not take any responsibility.
All copyrights are held by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark. Naming of particular products or brands should not be seen as endorsements.
2005-01-20
| Revision History | ||
|---|---|---|
| Revision 2.0.0 | 2004-05-11 | rw |
|
Compilation of several related wiki pages posted at http://www.saas.nsw.edu.au/koha_wiki/index.php?page=KohaOnWindows between 2003-07-16 and 2004-05-11. Initial XML markup by Stephen Hedges, 2004-12-12. |
||
Introduction to running Koha on Windows.
Yes, it is possible to install and run Koha on a Windows platform. Koha is written in Perl, stores its data in a MySQL database, and is accessed via an Apache webserver. All three of these supporting programs have distributions for Windows and are not hard to install. And they are all available without cost, just like Koha. A Windows install package is available for Koha that installs all the Koha files to the proper locations, installs required Perl modules, and handles necessary basic configuration to be able to run Koha with sample data.
If you are willing to read and follow some simple instructions, it's not very difficult. To be clear, it is not yet as simple as a single install. But it no harder than installing on a Linux box. You need to perform four separate installations as follows:
Apache Webserver
MySQL Database
Perl
Koha W32 install
Detailed instructions are provided for each install. Carefully follow the instructions as you do each install, and you should end up with a working version of Koha running with sample data. Each of the four installs provides an uninstall option. If you evaluate Koha and decide it's not for you, you can uninstall it from your system.
The basic program runs fine on Windows. However, there is one important feature that doesn't work yet. The Z39.50 client for downloading bibliographic records does not work on Windows. This is due to a required underlying Event module that hasn't been successfully ported to Windows yet. There may be a work-around, but it hasn't been tested. See the 'Want to Help?' section below if you'd like to be the one to test it.
We'd like to make the following improvements to Koha on Windows. Can you help us figure out to do any of the following? If so, please submit the solution to koha-win32 AT lists.sourceforge.net
Get the Z39.50 client for downloading bibliographic records working on Windows. See http://perl.z3950.org/support/windows.html or search Google for 'net::z3950 windows' for details on the problem.
Currently, Perl must be installed at C:\usr\bin\ for Koha to work. Do you know how to make Koha function when Perl is installed to some other location? I don't think symlinks are supported on Windows.
Improve the sample data set included with the install. Or provide a sample data set in another language.
Subscribe to the koha-win32 list at https://lists.sourceforge.net/lists/listinfo/koha-win32 and offer your suggestions and help to others on the list.
Download links for all necessary programs.
Two of the required supporting programs are supplied as Windows Installer (.msi) packages. The Windows Installer engine must be present in the operating system before a Windows Installer (.msi) package can be installed. Windows 2000 and XP include a version of Windows Installer, but Windows 9x and Windows NT do not. If you try to run the Apache or Perl installs and get a message asking what program to use to open the file, then you should go to http://support.microsoft.com/default.aspx?scid=kb;en-us;Q292539 and update your system with the Windows V2.0 installer for your operating system.
Apache Webserver is available from http://www.apache.org/dist/httpd/binaries/win32/
The W32 version file you are looking for is apache_2.0.47-win32-x86-no_ssl.msi MSI Installer Package or a more recent version if available. (If you are installing on Windows 98, do not use V2.0.44 - it had a bug). See KohaWin Installation for install instructions.
MySQL Database Server is currently available in two production releases. The older version 3 has been around for quite some time and version 4 was released this spring (2003). The Koha windows install has been tested with both versions, so either one should be ok. The older release is available from http://www.mysql.com/downloads/mysql-3.23.html. The recommended install package that you should download is mysql-3.23.58-win.zip (~13MB) or a more recent build of MYSQL V3.23.xx if available. MYSQL V4 is available from http://www.mysql.com/downloads/mysql-4.0.html. Look under the Windows downloads section for V4.0.15 or newer and download the package that includes an installer (~23MB). Some newer alpha or development releases may be available, but you should stick with a stable production release and not try an alpha release. See KohaWin Installation for install instructions.
Active State Perl is available from http://www.activestate.com/Products/ActivePerl/
Click the download link. You will be asked to register, but note that registration is NOT required to download - you can choose to skip it. The Koha W32 install packages now include the necessary Perl modules for both V5.6 and V5.8 of Active State Perl. So you can choose to download either the Windows MSI package for Active Perl 5.6.1 build 635 or the Windows MSI package for Active Perl 5.8.0 build 806 (or a more recent version of Active Perl V5.6.x.xxx or V5.8.x.xxx if available). When you install Activeperl BE VERY CAREFUL TO CHANGE THE INSTALL PATH ON THE SECOND OR THIRD DIALOG TO C:\usr\. See KohaWin Installation for detailed install instructions. It is not necessary to download any additional Perl modules. The Koha W32 installs include all necessary Perl modules for both V5.6 and V5.8 of Active Perl.
Koha W32 install packages are available for both a V1 stable production release and a V2 pre-release that still has some bugs, but is not far from a stable release. The V2 pre-release includes many new features including support for MARC and custom templates. The V1 release probably won't be supported much longer, so your best choice is probably the V2 prerelease, especially if you just want to do a trial installation to check out Koha's capabilities. See KohaWin Installation for detailed install instructions.
Koha V1.2.3 Stable Release for Windows (R2 Last updated July 1, 2003 - 4.5 MB)
This release is fairly old, does NOT include MARC support, and is no longer being actively developed. It is recommended that you try the latest release of Koha V2.0.0 below instead.
Koha V2.0.0 Stable Release for Windows (Install build R0 Last updated April 9, 2004 - 8.1 MB)
Check or subscribe to the koha-win32 mailing list (http://sourceforge.net/mail/?group_id=16466) to receive announcements of new releases when they become available.
Detailed install instructions - PLEASE review this page BEFORE you start.
Windows 98, Windows NT, Windows 2000, or Windows XP
(Apache and MySQL run as services on all of the above operating systems except Windows 98. On Windows 98, you will have to manually start Apache in a console window.)
There are a few things to be aware of:
There are usually two or more versions of Koha available for download. Some versions are stable release versions intended for actual production use. Others are release candidates (beta test versions) intended for testing new features and helping the developers with debugging. Take time to review the release notes and choose the version you want to test.
Evaluate Koha on a test machine, not on a production server. Even if you choose a stable version of Koha, the Windows install package referenced on these pages is still under development and should be considered a beta version. It may cause other Apache or MySQL applications to stop functioning.
It is important at least for now that you install each of the following applications to the specified path if you want to be sure Koha will work without doing a lot of extra manual configuration. In the future, we'll try to make the Koha on Windows install more flexible to work with Apache, MySQL and Perl at alternate locations. But for now, it may only work as specified.
The Z39.50 client for downloading bibliographic records does not work on Windows. This is due to a required underlying Perl Event module that hasn't been successfully ported to Windows yet. There may be a work-around, but it hasn't been tested. See the 'Want to Help?' section if you would like to be the one to test it.
See KohaWin Downloads page for download links for all necessary programs.
You can probably skip this step if installing to Windows 2000 or XP.
If you're installing to Windows 98 or NT and haven't already downloaded and installed MS Windows Installer 2.0 at some time in the past, do it now. Apache Webserver and Active State Perl are distributed using MS Windows Installer 2.0 and won't install if Windows Installer is missing. If you are not sure, just try doing Step 2. If it doesn't work, you need Step 1.
If you are installing on Windows 95, Windows XP, or if you use Zone Alarm (or other firewall), you should visit http://www.apache.org/dist/httpd/binaries/win32/ and read the appropriate warning notes before installing Apache.
Run the install, and follow the prompts. When you reach the dialog asking for:
Network Domain (e.g. somenet.com)
Server Name (e.g. www.somenet.com)
Administrator's email address
enter your domain if you know it. If not part of a domain, you can enter 'mydomain' or some other text - it should not make a difference if you are running Koha on a stand-alone computer. For the Server name, enter the fully qualified domain name of your computer if it is part of a domain. Otherwise, enter your computer name without the www. and .com. If you're not sure, make something up and the Koha install should correct it for you. For the Administrator's email address, enter an email address. (I don't think the email address is used by Koha). On the same dialog you'll also have a choice of 'for All users on port 80 ...' or 'only for the Current User, on Port 8080'. In all my testing, I chose the former, which is the default. On the following dialog, choose Typical Installation and the default install folder of C:\Program Files\Apache Group\. Let the install complete and reboot if asked to do so.
Do not install V2.0.44 on Windows 98 - it has a bug.
Unzip the file you downloaded and run SETUP.EXE. Install to the default location of C:\mysql. Choose a Typical Install. Let the install complete and reboot if asked to do so.
Run the file you downloaded. BE VERY CAREFUL TO CHANGE INSTALL PATH ON THE SECOND OR THIRD DIALOG TO C:\usr\. If you don't change it, it will default to the drive with most space and <drive letter>:\Perl\ and Koha will not work. Accept the default settings on the rest of the install dialogs. It is not necessary to install any additional Perl modules. The Koha Windows install includes the necessary Perl modules and will do that for you.
If you have previously installed Koha using an install package provided here, consider uninstalling the old version (especially if it was a test version) before installing a newer version. First, stop the MySQL server and make a backup of any data you want to keep. Then go to Control Panel -> Add\Remove Programs, and uninstall the previous version.
It is possible to install more than one version at a time and switch between them - see KohaWin Configuration for details.
Run the Koha Windows install. It will first check to be sure Apache, MySQL, and Perl are installed to the proper locations. If you get an error message about any of the required programs, it would be best to cancel the Windows Koha install and correct the problem before continuing. After a couple information dialogs, you'll be asked if you want to do a Full or Custom Install. You should choose to do a Full Install unless you are an experienced user and plan to manually configure all the programs to work together. On the Backup Replaced Files dialog, make a note of where backup files will be stored in case you need to access them. Continue and allow the install to complete.
Verify that both the Apache Webserver and the MySQL database are running:
On Windows 98, be sure to reboot your computer when the installs are finished. After reboot, the MySQL database should start automatically and you should see a Traffic Light icon in your System Tray that can be used to control the MySQL database. If the traffic light is green, the database is running. Click the Traffic Light to access WinMySqlAdmin and you'll be given options to Shutdown or Start the MySQL database server. On Windows 98, you need to manually start the Apache Web Server each time you want to run Koha. Do this by going to Start -> Programs -> Apache HTTP Server -> Control Apache Server and choose Start Apache in Console to start the server. You should get a DOS console window that needs to stay open but can be minimized. If the console window disappears after a brief moment, there is some problem with your Apache configuration.
If you chose to do a full install of Koha, you should have two icons in your System Tray - one a Feather and the other a Traffic Light. You can access the Apache Service Monitor by right clicking on the feather. You can use the Apache Monitor to start, stop, or restart the Apache server. You can use WinMySqlAdmin to control the MySQL database by clicking on the Traffic Light. You'll be given options to Shutdown or Start the MySQL database server. If the Traffic Light is green and the feather has a green arrow (rather than a red dot) in the small white circle, then both MySQL and Apache are running and you should be ready to run Koha.
Start your browser and access Koha. Once you are sure both Apache and MySQL are running, start Internet Explorer and type either opac or intranet on the address bar to access either the OPAC or Intranet interface to Koha. The default login for the Intranet interface is koha \ koha. If you use a Proxy Server, you may need to check Bypass proxy server for local addresses under Tools -> Internet Options -> Connections to stop IE from going out to the Internet to look for Koha.
If you evaluate Koha, and decide it's not for you, or if any of these installs causes problems with your computer, you can uninstall them using normal Windows procedures. Go to Control Panel -> Add/Remove Programs. Choose the programs one by one and then click on Add/Remove or Uninstall.
Helpful tools for managing Koha and manipulating data.
SQLyog is a easy to use, compact and very fast graphical tool to manage your MySQL database. Similar to MySQL Front and even a little more powerful. See the above website for a full list of features. This program was freeware when I added it to this list, but has now gone Shareware.
MySQL-Front is a free, powerful and easy-to-use Win32-Interface for web-workers dealing with MySQL-Databases. Not quite as powerful as SQLyog, but a little easier to use. With MySQL-Front you can:
create/drop databases
create/drop tables
edit/add/delete fields
edit/insert/delete records
edit BLOBs and MEMOs with Bitmap/GIF/JPEG-Support
execute (large) SQL-scripts
export table-structure and data into SQL-scripts or other databases
replicate databases between two hosts ("Export tables...")
save data to CSV-Files (ideal for working with MS-Excel) or HTML-tables
copy CSV-data/HTML-Tables to clipboard
copy tables to new table-names
manage users (new in 2.0: edit existing users)
write SQL-queries with syntax-highlighting
import data from ODBC-datasources
do table-diagnostics (check, optimize, repair, analyze)
and a lot more...
This program is no longer supported by its author, but it can still be obtained from the above page by clicking the download link in the upper right corner. It doesn't seem to work correctly on Windows NT, but does work on most other Windows versions.
CSVdb is a little utility for viewing, editing or rearranging data or columns in a comma delimited (or any other delimiter) text file. If you're trying to transfer data from another library system to Koha via a delimited text file, this utility can help.
Important config files, installing more than one Koha version and switching between versions, switching between Koha databases.
The following are important configuration files that affect the operation of Koha. You need to be aware of these files if you want to do any customization of settings from the standard windows install:
httpd.conf is the main configuration file for the Apache webserver. If you followed the install instructions on these pages, you will find httpd.conf at C:\Program Files\Apache Group\Apache2\Conf. More details coming soon ...
koha.conf is the main configuration file for Koha. It tells Koha which database to use, and the location of all the files for the Koha program. If you followed the install instructions on these pages, you will find koha.conf at C:\etc.
my.ini is the initialization file for the MySQL database server and for the WinMySQLadmin database administration tool. You should find my.ini in your Windows directory (C:\Windows or C:\WINNT). In this ini file under the [mysqld] section, the key basedir= is the path to where MySQL is installed and the datadir= specifies the path to where your data files are located. If you follow the instructions on these pages, basedir=C:/mysql and datadir=C:/mysql/data.
According to MySQL documentation, you should use a front slash / or a double back slash \\ for specifying paths since the back slash \ is the escape character in MySQL.
The data files used by Koha are determined by the combination of datadir= in my.ini and database= in koha.conf. If datadir=C:/mysql/data in my.ini and database=sample123 in koha.conf, then Koha will use the data files in the C:\mysql\data\sample123 folder. If you want Koha to use blank data instead, then edit C:\etc\koha.conf and change the database= line to database=blank123 and Koha will then use the data files in the C:\mysql\data\blank123 folder. Note that each database gets its name from the name of the subfolder in which its files are stored.
The Windows install package for Koha was written to make it possible to install more than one version of Koha on a single machine and then switch between them. This can be handy for someone who wants to evaluate both the current stable release of Koha as well as the latest test release. Or it could be useful for someone who wants to switch versions to assist the Koha development team with debugging and testing.
Now of course, each time you install a version of Koha, it makes changes to all of the configuration files listed in the Important Configuration Files section above to point everything to the latest version that is installed. However, once multiple versions are installed, it is possible to switch between them by simply swapping a couple of the configuration files and then restarting the Apache webserver.
If you'd rather not worry about the details of what needs to be swapped, you can use a little utility included in the W32 Koha installs (any installs dated July 1, 2003 or later) that will make the changes for you. Go to Start -> Program Files -> Koha and run SetKohaVersion, and you'll be asked which version of Koha to set as the default. You don't need to run this utility every time you start Koha. Once you set a default version, it will remain in effect until you run this utility again and change the version. The utility gets its list of versions from C:\etc\koahversions.txt, so if the list of choices is not correct, just edit this little text file and make the necessary corrections. All versions on the list should be formatted like KOHA V123 or KOHA V200RC1. Do not use decimal points in the version numbers.
Remember, the version change will not take effect until you restart the Apache webserver. On Windows NT, 2000 and XP, the utility will restart Apache for you. On Windows 98, you need to restart it manually.
The two configuration files that need to be swapped to switch versions are httpd.conf and koha.conf. To make it easy to switch version, a version specific copy of each of these configuration files is installed. For example, if you have installed Koha V1.2.3 and Koha V2.0.0RC1 and you look in C:\etc you'll find a koha.conf.123 with settings for V1.2.3 and a koha.conf.200RC1 with settings for V2.0.0RC1. The actual file named koha.conf that is being used by Koha will depend on which install you did last or which version you choose when you run the above utility. To switch versions, the contents of koha.conf are replaced with the contents of either koha.conf.123 or koha.conf.200RC1 depending on which version you choose to run.
At the same time, koha.conf is switched, a similar switch needs to be made for httpd.conf. Continuing our example, if you look in C:\Program Files\Apache Group\Apache2\Conf you'll find httpd.koha.123 for V1.2.3 and httpd.koha.200RC1 for V2.0.0RC1. The actual file that is used by Apache is httpd.conf. To switch versions, the contents of httpd.conf are replaced with the contents of either httpd.koha.123 or httpd.koha.200RC1 depending on which version you choose to run. The Apache webserver needs to be restarted before the change will take effect.
The above utility automates the above process. But you should understand what's happening because if you need to customize the configuration of either koha.conf or httpd.conf, you should also add your customizations to the version specific copies or else all your changes will be lost the next time you switch versions.
Suggestions on finding and fixing problems with Koha on Windows.
| 6.6.1.1. |
Apache Internal Server Error 500 |
|
You can troubleshoot internal server errors by looking at the Apache error log files. If you followed the install instructions on these pages, you'll find the apache log files at C:\Program Files\Apache Group\Apache2\logs. If you got the error while in the OPAC part of Koha, look in the opac-error_log. If you got the error while in the INTRANET part of Koha, look in the intranet-error_log. Open these files in notepad or another text editor and you should find some helpful information about your error. If you have trouble opening the log file because it is locked, make a copy of it first and then open the copy. Scroll all the way to the end of the file to see the most recent errors. See if you can figure out the error from the information given in the error log. Note that Apache logs even minor errors, so don't be surprised if you find lots of entries. If you need help, post just the last three or four lines of the error log to the koha-win32 mailing list, and we'll see if we can help. |
|
| 6.6.1.2. |
Typing OPAC or INTRANET in the address bar of my browser does not provide access to Koha |
|
Instead you get a message The page cannot be displayed. The Windows install provides access to the OPAC and Librarian (INTRANET) interfaces by using Apache name-based virtual hosts (see http://httpd.apache.org/docs-2.0/vhosts/ for Apache documentation on this). Two virtual hosts, one named OPAC and one named INTRANET, are configured in the Apache httpd.conf configuration file (open this file in notepad and scroll all the way to the end to see this configuration). For name-based virtual hosts to work, Windows name-resolution needs to be able to map both of the virtual host names (OPAC and INTRANET) to the IP address of your Koha server. To keep things simple, the Windows install assumes you are setting up a stand-alone Koha test server and uses an IP address of 127.0.0.1 (the local host address). Since a DNS server may not be available to a stand alone workstation and to keep things simple, the Windows install tries to provide name resolution for the OPAC and INTRANET virtual names by adding two lines to the hosts file in your C:\Winnt\system32\drivers\etc directory (for W9x this file is called lmhosts): 127.0.0.1 opac # Koha Library Software OPAC If you're not familiar with using a hosts file for name resolution, you can see http://www.labmice.net/networking/lmhosts.htm for more information. When you type INTRANET on the address bar of your browser, Windows should check the hosts file and resolve this to 127.0.0.1, connect to the Apache server and then feed the Apache server the virtual host name of INTRANET. When you type OPAC as the address it also resolves to 127.0.0.1 except this time it feeds the OPAC name to Apache. If no name is given, Apache is configured to display the OPAC interface. That's why you can run Koha OPAC by entering 127.0.0.1 or localhost. Troubleshooting ideas:
|