Koha on Windows

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:

  1. 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.

  2. 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.


1. Koha on Windows
1.1. Overview
1.2. How difficult is it to install Koha on Windows?
1.3. Does Koha work as well on Windows as it does on Linux?
1.4. Want to help improve this project?
2. KohaWin Downloads
2.1. Possible Windows System Update
2.2. Required Supporting Programs
2.3. Koha W32 Install Packages
3. KohaWin Installation
3.1. System Requirements
3.2. Before you start
3.3. Installation Instructions
3.3.1. STEP 1 - Update Windows Installer on Windows 98 or NT
3.3.2. STEP 2 - Install Apache to C:\Program Files\Apache Group\
3.3.3. STEP 3 - Install MySQL to C:\mysql
3.3.4. Install Perl to C:\usr\
3.3.5. STEP 5 - Consider Uninstalling any Previous Version of Koha
3.3.6. STEP 6 - Install Koha
3.4. Running Koha for the First Time
3.5. UnInstall Instructions
4. KohaWin Tools
4.1. Useful Tools for Managing a Koha Server and Database
5. KohaWin Configuration
5.1. Important Configuration Files
5.2. Changing the Database Used by Koha
5.3. Installing Multiple Versions of Koha (for testing or evaluation)
5.3.1. Details on what takes place when you run the above utility to switch versions
6. KohaWin Troubleshooting

1. Koha on Windows

Introduction to running Koha on Windows.

1.1. Overview

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.

1.2. How difficult is it to install Koha on Windows?

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.

1.3. Does Koha work as well on Windows as it does on Linux?

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.

1.4. Want to help improve this project?

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.

2. KohaWin Downloads

Download links for all necessary programs.

2.1. Possible Windows System Update

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.

2.2. Required Supporting Programs

Apache Webserver

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

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

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.

2.3. Koha W32 Install Packages

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.

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.

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.

3. KohaWin Installation

Detailed install instructions - PLEASE review this page BEFORE you start.

3.1. System Requirements

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.)

3.2. Before you start

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.

3.3. Installation Instructions

See KohaWin Downloads page for download links for all necessary programs.

3.3.1. STEP 1 - Update Windows Installer on Windows 98 or NT

Note

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.

3.3.2. STEP 2 - Install Apache to C:\Program Files\Apache Group\

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.

Important

Do not install V2.0.44 on Windows 98 - it has a bug.

3.3.3. STEP 3 - Install MySQL to C:\mysql

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.

3.3.4. Install Perl to C:\usr\

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.

3.3.5. STEP 5 - Consider Uninstalling any Previous Version of Koha

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.

Note

It is possible to install more than one version at a time and switch between them - see KohaWin Configuration for details.

3.3.6. STEP 6 - Install Koha

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.

3.4. Running Koha for the First Time

Verify that both the Apache Webserver and the MySQL database are running:

On Windows 98

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.

On Windows NT, 2000 or XP

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.

3.5. UnInstall Instructions

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.

4. KohaWin Tools

Helpful tools for managing Koha and manipulating data.

4.1. Useful Tools for Managing a Koha Server and Database

SQLyog - http://www.webyog.com/

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 - http://mysqlfront.venturemedia.de

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...

Note

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 - http://home.hccnet.nl/s.j.francke/t2t/text2table.htm

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.

5. KohaWin Configuration

Important config files, installing more than one Koha version and switching between versions, switching between Koha databases.

5.1. Important Configuration Files

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

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

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

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.

Important

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.

5.2. Changing the Database Used by Koha

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.

5.3. Installing Multiple Versions of Koha (for testing or evaluation)

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.

5.3.1. Details on what takes place when you run the above utility to switch versions

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.

6. KohaWin Troubleshooting

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
127.0.0.1 intranet # Koha Library Software INTRANET

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:

  1. Were you logged in as a local administrator when you did the install? If not, the install probably could not modify your hosts file. Reinstall Koha as a local admin or manually add the above two lines to your hosts file.

  2. Check name resolution by opening a DOS command prompt window and typing PING OPAC and then PING INTRANET. Both of these commands should result in replies from 127.0.0.1. If not, something is wrong with your hosts name resolution. See the above link for more help.

  3. Check that Enable LMHOSTS lookup is checked under Network Places -> Properties -> Local Area Connection -> Properties -> TCP/IP -> Properties -> Advanced -> WINS tab.

  4. Make sure your browser isn't going out to the Internet to try to resolve the OPAC and INTRANET names. 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.

  5. It also could be that you have higher than the recommended version of the SQL database server. You might want to check that.