VuFind Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Installation ======

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

These instructions assume that you are installing all software components separately.  Many developers use [[http://www.apachefriends.org/en/xampp-windows.html|XAMPP]] to install Apache, MySQL and PHP as a bundle.  XAMPP should not be used in a production environment, but it may save some time for a test server -- however, it works differently than separate component installation, so watch for XAMPP-related notes as you read.

===== Installation Procedure =====


==== 1. Download VuFind ====

Extract the VuFind source -- you can download it [[http://vufind.org/downloads.php|here]].  The .zip format is usually the most convenient option for use in Windows.  These instructions assume that you use a target path of c:/vufind. 





==== 2. Install the Apache HTTP Server ====

You can download the server [[http://httpd.apache.org/download.cgi|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

// IMPORTANT: If your VuFind instance will include records with slashes in their IDs, you need to add "AllowEncodedSlashes on" to the appropriate <nowiki><VirtualHost></nowiki> section of your Apache configuration! //
==== 3. Install MySQL ====

You can download the database from [[http://dev.mysql.com/downloads/mysql/5.0.html#downloads|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.

=== Troubleshooting libmysql.dll ===

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 [[windows#install_the_java_jdk|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 ====

=== Install ===

You can download PHP [[http://windows.php.net/download/|here]].  Choose the thread safe version unless you have a specific reason to use the non-thread safe version.

:!: Pay attention to which version of Apache you downloaded -- PHP and Apache will integrate better if they are built for the same architecture (32-bit vs. 64-bit) using the same compiler. For example, if you downloaded a 32-bit (x86) version of Apache, you should not try to install a 64-bit (x64) version of PHP.

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

  * GD2 (optional, but recommended for best cover image display)
  * Internationalization (intl)
  * LDAP (optional)
  * Multi-Byte String (optional, but recommended)
  * MySQL
  * MySQLi
  * PDO (with MySQL)
  * XSL

=== Set up Environment ===

Make sure that your Windows PATH environment variable includes the location of PHP (this location was specified during installation).  This will allow you to type "php" from any command prompt in order to run scripts.  For details on modifying environment variables, see [[#Appendix: Editing Environment Variables]].

=== Notes ===

  * 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.
  * 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; Google searches for error messages are usually helpful for this.
  * If you are using XAMPP instead of separate components, the installation process won't ask you about extensions.  Instead, you will have to manually uncomment the relevant lines in your php.ini file.
  * If you are a Voyager library, you will also need to install the PHP OCI Driver for Oracle – see [[php_oci|this page]] for detailed instructions.

==== 5. Install the Java JDK ====

Next install JDK (the Java Development Kit) on the server – VuFind's searching back-end and MARC indexing tools rely on Java. Note that some VuFind components may be able to run using only the JRE (Java Runtime Environment), but the JDK is strongly recommended, and required for proper MARC indexing after release 3.1.

You can download the JDK [[http://java.sun.com/javase/downloads/?intcmp=1281|here]].  You should be able to use all the default installation options.

Set a system environment variable named JAVA_HOME pointing to the path to your Java installation (probably something like c:\Program Files\Java\jdk1.x.y_z).  For details on how to do this, see [[#Appendix: Editing Environment Variables]].

==== 6. Run VuFind Installation Script ====

The groundwork is set, so you can now run VuFind's install script to set up your basic configuration. 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").
  * Type "php install.php" (without the quotes) and hit Enter.

You will be prompted for several details; you can accept the defaults for now – you can run the installer again later if you need to make changes.

==== 7. Configure VuFind ====

=== Set up Environment Variables ===

The final output of the install script from the last step will tell you to set up VUFIND_HOME and VUFIND_LOCAL_DIR environment variables.  If you are not sure how to do this, see [[#Appendix: Editing Environment Variables]].

=== 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/local/httpd-vufind.conf

(Be sure to adjust the path if your file is located somewhere other than c:/vufind/local).

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.

In order to properly handle network timeouts you should modify PHP's maximum execution time and default socket timeout settings. You can do this either in the webserver's php.ini or by adding the following lines to the http-vufind.conf file:

    php_value default_socket_timeout 25
    php_value max_execution_time 30

You can choose lower or higher values (both in seconds) depending on your environment. The socket timeout should always be lower than the max execution time. **This is 100% windows specific** -- the time to connect to a remote host (default_socket_timeout) counts towards the maximum time a PHP script is allowed to run. On *nix platforms it does not.

== 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 configuration, 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.//

=== Configuring Solr ===

:!: Important -- the instructions in this section are probably not necessary for VuFind 3.0 or newer; please ignore unless you are using an older version. :!:

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:

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

to this:

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

==== 8. Start Solr ====

Now that VuFind is installed and basic configuration is complete, you can start the Solr server running.  See the [[administration:starting_and_stopping_solr|Starting and Stopping Solr]] page for details.

==== 9. Final Configuration ====

Open a web browser, and browse to this URL:

  http://your-server-name/vufind/Install/Home

(Replace "your-server-name" with the address you wish to use to access VuFind; replace "vufind" with your custom base path if you changed the default setting during installation).

=== Troubleshooting ===

If you see a blank white screen, something is wrong.

  * Check your Apache error log for messages -- see [[#Troubleshooting_Apache|Troubleshooting Apache]] above.
  * If that does not help, try editing c:/vufind/local/httpd_vufind.conf and uncommenting the "SetEnv VUFIND_ENV development" line -- after an Apache restart, this will put VuFind into development mode (which will display more detailed error messages if the code is capable of running).

If you are still stuck, try one of the mailing lists on the [[http://vufind.org/support.php|support page]].

=== Auto-Configuration ===

If installation was successful, you should now see an Auto Configure screen.

Some items on the list will be marked "Failed" with "Fix" links next to them.

Click on each Fix link in turn and follow the on-screen instructions.

After an issue is successfully resolved, you can click the "Auto Configure" breadcrumb to go back to the main list and proceed to the next problem.

Notes:

  * To set up VuFind's database, you will need to have the root password you set when installing MySQL.

=== Locking Down Configurations ===

Once all configuration issues are successfully resolved, you will see a "Disable Auto Configuration" link on the "Auto Configure" page.  Click this to prevent future access to the install script.  If you need access again in the future, you can re-enable it by manually editing your [[configuration:files:config.ini]] file.

==== 10. Import Records ====

Import bib records using the instructions on the [[:indexing]] 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 [[http://vufind.org/jira/browse/VUFIND-630|VUFIND-630]] JIRA ticket.

==== Appendix: Editing Environment Variables ====

These instructions will help you edit Windows environment variables:

=== 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 if you need to create a variable
  * To modify an existing variable, double-click on it in the user variables box
VuFind Documentation

Site Tools

Page Tools
