About Features Downloads Getting Started Documentation Events Support GitHub

Site Tools


legacy:installation:windows

Installation

These instructions are for use with VuFind 1.x; for later versions, see the 2.x instructions.

These instructions assume that you are installing your MySQL database on the same server as VuFind itself and that you are using an installation path of c:\vufind

Requirements

To satisfy VuFind's dependencies, make sure you install the software versions recommended on the requirements page. You may use other versions at your own risk.

greg_pendlebury (Nov 08) : I usually run XAMPP in my laptop for little dev projects. If you install this it replaces Apache, PHP and MySQL.

rmchugh (April 12) : Note that if you use xampp you will need to ensure the following line is present in the php.ini in xampp/php/: extension=php_xsl.dll Otherwise operations that require the xslt processor will not work properly.

Installation Procedure

1. Download VuFind

Extract the VuFind source – you can download it here. You can find help with extracting tar.gz files under Windows here. These instructions assume that you use a target path of c:/vufind.

2. Install the Apache HTTP Server

You can download the server here. Typical installation options found in the install wizard should work fine.

Make sure that the mod_rewrite module is activated – edit the Apache configuration file (something like c:\Program Files\Apache Software Foundation\Apache#.#\conf\httpd.conf, easily available in Apache's Start Menu group under Apache HTTP Server, Configure Apache Server) and check that this line is uncommented (doesn't have a # in front of it):

  LoadModule rewrite_module modules/mod_rewrite.so

Also make sure that the DirectoryIndex command includes index.php. It should like something like this:

  DirectoryIndex index.html index.php

3. Install MySQL

You can download the database from here. You should be able to get by with the default options of a typical installation found in the wizard. If you set a root password (a good idea), be sure to take note of it.

One important piece of the MySQL installation is the library file, libmysql.dll. If Windows cannot find this file, you may get errors about a missing database driver when you try to view pages in VuFind. Depending on which operating system/software versions you end up using, you may not have to do anything special to make this work. However, if you run into trouble after completing the other steps of the VuFind installation process, try these options:

1.) Make sure that libmysql.dll is in your PHP directory and that your PHP directory is included in your system path (as described below in the Java JDK step).

2.) If libmysql.dll is not in your PHP directory, it may be in your MySQL directory (usually something like C:\Program Files\MySQL\MySQL Server 5.0\bin). It may help to add this directory to your system path as well. Warning: If the file is in BOTH your PHP AND MySQL directories, the PHP version is probably the correct one, and using the MySQL version may cause problems. In some scenarios, you may actually need to REMOVE the MySQL directory from your path to solve this problem.

3.) As a last resort, you may try copying libmySQL.dll to your c:\windows\system32 folder. THIS IS NOT RECOMMENDED, as it may make future upgrading more difficult.

4. Install PHP

You can download PHP here. Choose the thread safe version unless you have a specific reason to use the non-thread safe version.

When prompted, choose the appropriate version of Apache and provide your configuration directory (i.e. c:\Program Files\Apache Software Foundation\Apache#.#\conf\); if you get an error message, don't panic – you can manually correct it later (see notes under the VuFind configuration step below).

When you reach the “Choose Items to Install” stage of the install process, be sure to install PEAR (found under Extras) and these extensions (found under PHP / Extensions):

  • LDAP (optional)
  • MySQL
  • PDO (with MySQL)
  • Pspell (optional)
  • XSL
  • GD2 (optional, but recommended for best cover image display)
  • Multi-Byte String (optional, but recommended)

Note: Don't panic if you forget to add a component on your first installation. You can always run the installer again to update your installation with additional modules.

Note: It is possible that PHP will install some extensions without all of the necessary library files. If this happens, starting up PHP will lead to a series of pop-up alerts. To fix the problem, simply edit the php.ini file (usually found in c:\Program Files\PHP\, and also available via Start Menu shortcut) and comment out (by putting a semi-colon in front) the offending modules (found in lines like extension=php_*.dll). If you actually need some of the affected modules, you may have to track down copies of the missing files (for example, to get the php_pspell module working, you will need to first install GNU Aspell and put the aspell-15.dll file somewhere your system can find it (for example, c:\windows\system32)).

Note: If you are a Voyager library, you will also need to install the PHP OCI Driver for Oracle – see this page for detailed instructions.

Activate PEAR

You should now set up the PEAR code used for downloading standard code libraries for PHP. Go to the command prompt and type these commands:

  cd "c:\Program Files\PHP"
  go-pear

Note: Under Windows 7, the path to PHP may actually be “c:\Program Files (x86)\PHP” – substitute as needed.

Follow the on-screen prompts; you should be able to leave settings at the defaults unless you want to change them for some reason.

greg_pendlebury (July 2010): The latest XAMPP installers (1.7.0+) do not require go-pear to be run at all. The comment below only applies for older versions.

greg_pendlebury (Nov 2008): The XAMPP installer doesn't prepare PEAR to work the way VuFind expects it to. If you are using XAMPP instead of the separate Apache/PHP/MySQL installations, you may need this solution (read the comments too). Apply this before running the install script or manually installing PEAR modules.

PEAR behind a Proxy

If you are behind a proxy server when performing the install, PEAR will need to know about your proxy server before the installation will work. Just before running the installation script you will need to execute this command:

 pear config-set http_proxy http://{your.proxy.server}:{port}

Download Smarty

To install the template system used by VuFind, you need to download Smarty from here. VuFind was designed with Smarty 2.6.26 in mind; newer versions can cause problems. Extract the Smarty*.zip file and move the contents of the resulting libs folder into a Smarty folder under your PHP directory's PEAR folder.

It is important that you install the CONTENTS of the libs folder and not the folder itself. With a standard PHP install, this means that the c:\Program Files\PHP\Pear\Smarty folder should contain Smarty.class.php (among other files). If these files end up in the c:\Program Files\PHP\Pear\Smarty\libs folder instead, you will run into errors!

greg_pendlebury (Nov 08) : With XAMPP the path required was c:\xampp\php\PEAR\Smarty

5. Install the Java JDK

You can download the JDK here. You should be able to use all the default installation options.

Set a system environment variable named JAVA_HOME to the path to your Java installation:

Windows XP or earlier

  • Open Control Panel
  • Go to System (available in Classic View under XP)
  • Advanced tab
  • Environment Variables

Windows Vista/7

  • Open Start Menu
  • Right click “Computer” or “My Computer”
  • Click Properties
  • Click “Advanced system settings”
  • Click “Environment Variables”

All versions (after following version-specific instructions above)

  • In the lower box marked System variables, click on New
  • Variable name: JAVA_HOME
  • Variable value: [c:\path\to\java\] (probably something like c:\Program Files\Java\jdk1.x.y_z)
  • While we are here, double click on the PATH variable in the user variables box and add C:\path\to\php;c:\path\to\php\pear. If no PATH variable exists, create it and add the same details.
    • (Note: In many cases, the PHP and PEAR paths will be the same: C:\Program Files\PHP\; it is also possible that the install process already added these to the path for you).

Reboot. Windows may not recognize the PATH changes otherwise.

6. Run VuFind Installation Script

Starting with VuFind 1.0RC2, a Windows installation script is included with VuFind. This takes care of automatically setting up some of the final details necessary to run VuFind. To run the script, just follow these steps:

  • Go to Start>Run and enter “cmd” with no quotes (to get to a command prompt).
    • In Windows 7, there is no “Run” option – just start typing in the search box. You may need to right-click on the “cmd” command and run as administrator to ensure that everything gets installed with appropriate permissions.
  • Switch to your VuFind directory (i.e. “cd c:\vufind”).
  • If you are behind a proxy server remember to run the pear proxy command mentioned above.
  • Type “install” (without the quotes) and hit Enter.

You will be prompted for database settings; most can be left at their defaults. Now is when you'll need to remember the root MySQL password if you set one up earlier. You may see some minor errors and warnings while everything gets set up – this is normal, so don't panic!

If you are installing an old version of VuFind without an install script, please see Manually Installing VuFind. VuFind has not required manual installation in a very long time, so this is unlikely to ever be necessary.

mbeccaria (12-10-2009): In my install I ran into a minor hitch and had to edit the PHP_PEAR_PHP_BIN variable from “.\php.exe” to the full path “C:\Program Files\PHP\php.exe” via the windows environment variables (right click My Computer → Properties → Advanced Tab → Environment Variables → PHP_PEAR_PHP_BIN → edit, change the value. Be sure to restart cmd.exe after you change the variable.

greg_pendlebury (July 2010): If you installed XAMPP, PHP_PEAR_PHP_BIN won't even exist. You can either create it as per above, or add the the XAMPP path to the system PATH variable. Something like 'C:\xampp\php' whichever option you take.

7. Configure VuFind

Linking VuFind to Apache

Edit the Apache configuration file (something like c:\Program Files\Apache Software Foundation\Apache#.#\conf\httpd.conf, easily available in Apache's Start Menu group under Apache HTTP Server, Configure Apache Server) and add:

  Include c:/vufind/httpd-vufind.conf

Change all the /usr paths (on lines 2 and 3 plus close to the bottom in the AuthUserFile setting) to Windows based paths (i.e. change /usr/local/vufind/… to c:\vufind\…) in the c:\vufind\httpd-vufind.conf file.

Once the configuration files are edited, you need to restart Apache for them to take effect – you can do this from the Start menu under Apache HTTP Server, Control Apache Server, Restart.

Troubleshooting Apache

System-specific configuration issues may prevent things from working at this point. A misconfiguration may prevent Apache from starting or may give you “Forbidden” errors when you try to access VuFind. This section contains some tips on resolving any problems.

If your PHP installation was unable to automatically add PHP to the Apache logs, you may need to add these lines to your Apache configuration, somewhere above the “Include” that loads http-vufind.conf:

  LoadModule php5_module "c:\Program Files\PHP\php5apache2_2.dll"
  AddType application/x-httpd-php .php
  PHPIniDir "c:\Program Files\PHP\"

(note that you may need to substitute a slightly different path to PHP depending on your Windows version – in Windows 7, it will be “c:\Program Files (x86)\PHP\”)

It is often helpful when troubleshooting to look at the Apache logs – you can find these in the Start menu under Apache HTTP Server, Review Server Log Files.

mike_beccaria (Jun 09) : Add “Options All” to the httpd-vufind.conf file if you are getting an “access Denied” on the homepage and a “Directory index forbidden by option directive” error in the apache error.log.

demiankatz (Jul 09) : if the PHP install added multiple PHPIniDir and LoadModule entries to the bottom of httpd.conf and this is preventing Apache from starting, comment out the duplicate ones and leave only the first pair intact.

Setting up VuFind Itself

Edit c:/vufind/web/conf/config.ini. Many of the settings are self explanatory and institution-specific. The following must be set specifically for Windows:

  [Site]
  path            = /vufind
  url             = http://localhost/vufind
  local           = c:/vufind/web
  [Database]
  database        = mysql://[username]:[password]@localhost/vufind
  schema_location = c:/vufind/web/conf
  class_location  = c:/vufind/web/services/MyResearch/lib

Be sure to replace any /usr/local/ references in the config file not listed above with c:/ as well.

Troubleshooting VuFind

If something isn't quite right with VuFind, you will often discover that going to its URL simply gives you a blank white screen. This is because error output is disabled by default. For troubleshooting purposes, you can turn it back on by uncommenting the error-related php_value settings in c:\vufind\httpd-vufind.conf – this will usually give you a better idea of what is wrong (don't forget to restart Apache so it takes effect). Setting the debug setting to true in c:\vufind\web\conf\config.ini is also sometimes helpful when tracking down a problem.

Configuring SolrMarc

If you are going to be loading MARC records into VuFind, edit c:/vufind/import/import.properties and change references to /usr/local/vufind to use c:/vufind instead. If you plan to load authority records, the same thing needs to be done in c:/vufind/import/import_auth.properties.

Configuring Solr

The config files for each Solr index are currently set up to use relative paths. Because Windows services run in a different user context with different working directories, Solr may have problems finding its index files. If you skip this step, you may find that searches never yield any results. To be on the safe side, you should reconfigure Solr to explicitly point out where the index files live.

In the following files:

  c:/vufind/solr/biblio/conf/solrconfig.xml
  c:/vufind/solr/authority/conf/solrconfig.xml
  c:/vufind/solr/stats/conf/solrconfig.xml

Find the node:

  \config\dataDir

And change the relative paths currently there to:

  c:/vufind/solr/biblio
  c:/vufind/solr/authority
  c:/vufind/solr/stats

For example, you would change this:

  <dataDir>${solr.data.dir:./solr/biblio}</dataDir> 

to this:

  <dataDir>c:/vufind/solr/biblio</dataDir> 

8. Start VuFind

Now that VuFind is installed and basic configuration is complete, you can start the server running. See the starting and stopping Solr page for details.

9. Import Records

Import bib records using the instructions on the importing records page.

Appendix: General Notes

If you are using VuFind's Wikipedia author information module (which is turned on by default), you may run into problems unless you increase Apache's heap size setting. For more details, see the VUFIND-630 JIRA ticket.

legacy/installation/windows.txt · Last modified: 2016/08/10 10:35 by demiankatz