This documentation will help you install VuFind 1.3. Documentation for the previous major release, VuFind 1.2, can be found here, but using the old version is NOT recommended.

These instructions assume that you are starting with a clean installation of Fedora 11 or newer. If you already have a Fedora server, you will be able to skip some steps, but you may have to reconfigure some existing software.

Install Fedora. Notes:

• These instructions were originally written with Fedora 11 in mind. They have also been successfully tested with Fedora 12, 14 and 16.
• Fedora 15 seems to have some SELinux changes that may cause problems, but the instructions will still work if you are willing to disable SELinux protection – if a better solution is found, feel free to add more notes here. Fedora 16 seems to solve the problem, so if possible, just use the newer version of the OS.
• You can obtain a free copy of the software and find installation instructions at fedoraproject.org. If you prefer a bare-bones web server over the GUI features provided by the default Live CD, you can install the Minimal system from the DVD available here. If you do boot up from the Live CD, be sure you install the operating system to your hard drive BEFORE installing VuFind; it may not work well if you try to run it entirely from the bootable CD.

Once Fedora is installed, you can script nearly the entire process of VuFind installation. Skip to A (Mostly) Scripted Default Installation for the automated process. Continue reading Detailed Installation Instructions to install manually and read explanations of each step of the process.

One of the key features that distinguishes Fedora from some other Linux distributions is its use of the SELinux security module. You can read a basic introduction to SELinux here (pdf). The greater security level makes installation a bit more complicated. The instructions below should get VuFind working without forcing you to take down your security; however, I'm not an expert on this, so feel free to edit the document and improve my suggested commands if there is a better way.

Also note that SELinux can block a lot of things – if security is misconfigured, it will prevent Apache from talking to Solr and your ILS; if library files have the wrong permissions, it won't let code load or execute; etc. If you run into problems during installation, be sure to add SELinux to your troubleshooting checklist, and remember that you can temporarily turn it off if you need to confirm whether or not it is really the cause of your troubles. (But be sure to turn it back on again after you're done testing – I encourage you to solve things by working within the system, even though the temptation to turn it off for good may be strong at times!) These instructions should get you through without any trouble, but if you run into problems outside the scope of the instructions, hopefully some of the commands used here will help you do further research on your own.

Following these steps will give you a running instance of VuFind. Note that Fedora puts you in a graphical desktop by default – to enter all of the commands described below, you will need to go to a command prompt, which you can access under Applications, System Tools, Terminal in the top menu.

The commands below assume that you have root access to the system. If you are logged in as a user account, you can gain root access by entering:

su

You will be prompted for the system's root password.

Root access can be dangerous, so be sure to exit out of the root account as soon as you are done with the necessary work!

The first step is to make sure you have the latest patches installed.

yum update

Now install the Apache web server. This will facilitate communication between VuFind and web browsers.

The basic Fedora install should come with Apache, but you can use this line to double-check and find out which version you have:

yum install httpd

VuFind requires that the mod_rewrite module be enabled (this is used to form the URLs for accessing VuFind) – like Apache itself, this should already be done for you by default in Fedora, so you shouldn't have to change anything. If your installation has been changed from the defaults, you can re-enable it by making sure that this line in /etc/httpd/conf/httpd.conf is uncommented (does not have a pound sign in front of it):

LoadModule rewrite_module modules/mod_rewrite.so

If the server had to be reconfigured or is not already running, you can make sure it's running and up to date like this:

apachectl restart

VuFind uses the MySQL database for storing user comments, tags and other information. You should install this component next:

yum install mysql-server

Once MySQL is installed, you should start it up:

service mysqld start

For security reasons, it's also a good idea to set a root password for the database; this command will guide you through the process:

/usr/bin/mysql_secure_installation

Most of VuFind is written using the PHP language. We must install this next, being sure to enable modules for key technologies used by VuFind (MySQL, LDAP, etc.)

yum install php php-devel php-pear php-ldap php-mysql php-xsl php-pspell php-gd php-mbstring

Note that the php-ldap library is only needed if you will be using LDAP authentication, and the php-pspell library is not used at all but might feature in future spelling-related enhancements; you can exclude these packages if you like. The php-gd package is also optional, though including it will ensure better support for cover images.

If you are a Voyager library, you will also need to install the PHP OCI Driver for Oracle – see the section below for detailed instructions.

If you will be accessing a Sybase database (e.g. for the Horizon LMS), also install php-mssql.

yum install php-mssql

Next install JDK 6 (the Java Development Kit) on the server – VuFind's searching back-end relies on Java.

yum install java-1.6.0-openjdk-devel

Note: You can run the Jetty server with the JRE, but in order to ensure that your server can run with the ”-server” to enable server heuristics, you need to install the JDK.

All the prerequisites are in place, so now for the fun part – downloading and installing VuFind itself! The easiest method is through the Subversion tool, so these steps install Subversion and use it to load VuFind:

yum install subversion
svn export --force https://vufind.svn.sourceforge.net/svnroot/vufind/releases/VuFind-1.3 /usr/local/vufind

Appropriate security permissions need to be set up so Apache can access the VuFind code. The chcon line sets file permissions so Apache is allowed to load the files. The setsebool command allows Apache to communicate with itself internally, which is necessary to access the search back-end.

cd /usr/local/vufind/web
chcon -R unconfined_u:object_r:httpd_sys_content_t:s0 *
setsebool -P httpd_can_network_relay=1

It is also necessary to make a few directories writeable so VuFind can generate cache files:

chmod 777 /usr/local/vufind/web/interface/compile
chmod 777 /usr/local/vufind/web/interface/cache 
chmod 777 /usr/local/vufind/web/images/covers/*
chcon -R unconfined_u:object_r:httpd_sys_rw_content_t:s0 /usr/local/vufind/web/interface/compile
chcon -R unconfined_u:object_r:httpd_sys_rw_content_t:s0 /usr/local/vufind/web/interface/cache
chcon -R unconfined_u:object_r:httpd_sys_rw_content_t:s0 /usr/local/vufind/web/images/covers/*

Apache needs to have some extra VuFind settings loaded. Run these commands to set the appropriate security context for VuFind's configuration and then link it with Apache.

chcon system_u:object_r:httpd_config_t:s0 /usr/local/vufind/httpd-vufind.conf
ln -s /usr/local/vufind/httpd-vufind.conf /etc/httpd/conf.d/httpd-vufind.conf

Apache needs to be restarted so the changes can take effect:

apachectl restart

If Apache will not restart successfully, it probably has to do with SELinux permissions; if you are unable to get things working with the symbolic link, you may have better luck deleting the link and simply copying the configuration file into place:

rm /etc/httpd/conf.d/httpd-vufind.conf
cp /usr/local/vufind/httpd-vufind.conf /etc/httpd/conf.d/httpd-vufind.conf
apachectl restart

If you take this approach, remember that you will have to edit the copy in /etc/httpd/conf.d/httpd-vufind.conf rather than the original in /usr/local/vufind/httpd-vufind.conf when making configuration changes.

The VuFind install process needs the wget command to download components; make sure it is available:

yum install wget

The groundwork is set, so you can now run VuFind's install script to set up final details. This will prompt you 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!

cd /usr/local/vufind
/usr/local/vufind/install

Scripts for running and updating VuFind need to be made executable so they can run from the command line:

chmod +x /usr/local/vufind/vufind.sh
chmod +x /usr/local/vufind/import-marc.sh

Smarty (the template engine installed by the install script) needs to be given permissions that will allow PHP to access it:

chcon -R unconfined_u:object_r:usr_t:s0 /usr/share/pear/Smarty/*

Everything is set up - proceed to Configuring and Starting VuFind below.

You can use this script to (mostly) install everything to get VuFind running on Fedora. Just save this script as fedora_setup.sh, switch to root access and run it. IF YOU ALREADY FOLLOWED THE STEP-BY-STEP INSTRUCTIONS ABOVE, YOU CAN SKIP THIS – IT DOES THE SAME THING!

su
sh fedora_setup.sh

You will be prompted along the way for confirmation of various package installs (just answer yes or edit the script to force agreement) as well as a few security settings (fill these in as you see fit).

If you are a Voyager library, you will also need to install the PHP OCI Driver for Oracle - see the section below for detailed instructions.

After running the script, proceed to Configuring and Starting VuFind below.

#!/bin/bash
 
# Script for installing VuFind 1.3 on Fedora
# This does not include the OCI8 libraries
 
# Set some variables
VUFIND_SVN="https://vufind.svn.sourceforge.net/svnroot/vufind/releases/VuFind-1.3"
VUFIND_HOME="/usr/local/vufind"
 
# Update the system and install software
yum update
yum install httpd mysql-server php php-devel php-pear php-ldap php-mysql php-xsl php-pspell java-1.6.0-openjdk-devel
 
# Start MySQL and set up security
service mysqld start
/usr/bin/mysql_secure_installation
 
# download VuFind using Subversion
yum install subversion
svn export --force $VUFIND_SVN $VUFIND_HOME
 
# Fail if we couldn't download the file -- we don't want to continue without it!
if [ ! -f $VUFIND_HOME/install ]
then
	echo FATAL ERROR -- could not load VuFind from $VUFIND_SVN
	exit
fi
 
# Set permissions so apache can access appropriate directories and services.
cd $VUFIND_HOME/web
chcon -R unconfined_u:object_r:httpd_sys_content_t:s0 *
setsebool -P httpd_can_network_relay=1
 
# set up Apache for VuFind and reload configuration
chcon system_u:object_r:httpd_config_t:s0 $VUFIND_HOME/httpd-vufind.conf
ln -s $VUFIND_HOME/httpd-vufind.conf /etc/httpd/conf.d/httpd-vufind.conf
apachectl restart
 
# Finalize the installation 
cd $VUFIND_HOME
yum install wget
$VUFIND_HOME/install
chmod +x $VUFIND_HOME/vufind.sh
chmod +x $VUFIND_HOME/import-marc.sh
chmod 777 $VUFIND_HOME/web/interface/compile
chmod 777 $VUFIND_HOME/web/interface/cache 
chmod 777 $VUFIND_HOME/web/images/covers/*
chcon -R unconfined_u:object_r:httpd_sys_rw_content_t:s0 $VUFIND_HOME/web/interface/compile
chcon -R unconfined_u:object_r:httpd_sys_rw_content_t:s0 $VUFIND_HOME/web/interface/cache
chcon -R unconfined_u:object_r:httpd_sys_rw_content_t:s0 $VUFIND_HOME/web/images/covers/*
chcon -R unconfined_u:object_r:usr_t:s0 /usr/share/pear/Smarty/*

There are a few steps if you need to install the OCI8 libraries.

First, upgrade pear to the latest version (this won't do anything if you are already up to date).

pear upgrade pear

Create a directory to store the Oracle code and then switch to it:

mkdir -p /opt/oracle
cd /opt/oracle

Now, you need to get the Oracle Instant Client (at a minimum you need Basic and SDK zip files). You will need to accept a license agreement and log in to Oracle's site (free account creation) in order to download the files - grab them with your web browser (be sure to select the appropriate Linux code for your hardware) and then transfer them to the /opt/oracle directory that you just created.

Unzip the files (note that some versions of the libraries may have longer filenames - substitute as necessary):

unzip basic.zip
unzip sdk.zip

Set up some symbolic links to make the paths simpler and easier to upgrade:

ln -s instantclient_11_1 instantclient
cd /opt/oracle/instantclient
ln -s libclntsh.so.11.1 libclntsh.so
ln -s libocci.so.11.1 libocci.so

Note that numbers in some filenames may vary depending on the version you downloaded.

Set up security permissions so other code can access the libraries:

chcon -t textrel_shlib_t /opt/oracle/instantclient/*.so
execstack -c /opt/oracle/instantclient/*.so.*
setsebool -P httpd_execmem 1

Now add the Instant Client to the system dynamic library loader.

echo /opt/oracle/instantclient > /etc/ld.so.conf.d/oracle-instantclient

Install some tools you will need to build libraries:

yum install gcc

Now compile and install the OCI8 package with PECL

pecl install oci8

Note, you will be prompted for the instantclient directory, so when you're prompted, just enter

instantclient,/opt/oracle/instantclient

Now install the PHP extension and restart Apache

chcon system_u:object_r:textrel_shlib_t:s0 /usr/lib/php/modules/oci8.so
chmod +x /usr/lib/php/modules/oci8.so
echo extension=oci8.so > /etc/php.d/oci8.ini
apachectl restart

If VuFind doesn't work for you with just the OCI8 package installed, you may also need PDO_OCI. (Notes adapted from this page).

Download and unzip the package:

mkdir -p /tmp/pear/download/
cd /tmp/pear/download/
pecl download pdo_oci
tar xvf PDO_OCI-1.0.tgz
cd PDO_OCI-1.0

Edit the config.m4 file…

Add these lines:

    elif test -f $PDO_OCI_DIR/lib/libclntsh.$SHLIB_SUFFIX_NAME.11.1; then
      PDO_OCI_VERSION=11.1    

above these lines:

    elif test -f $PDO_OCI_DIR/lib/libclntsh.$SHLIB_SUFFIX_NAME.10.1; then
      PDO_OCI_VERSION=10.1    

Also add these lines:

      11.1)
        PHP_ADD_LIBRARY(clntsh, 1, PDO_OCI_SHARED_LIBADD)
        ;;

above these lines:

      *)
        AC_MSG_ERROR(Unsupported Oracle version! $PDO_OCI_VERSION)
        ;;

Now build everything:

phpize
mkdir -p /opt/oracle/instantclient/lib/oracle/11.1
ln -s /opt/oracle/instantclient/sdk /opt/oracle/instantclient/lib/oracle/11.1/client
ln -s /opt/oracle/instantclient /opt/oracle/instantclient/lib/oracle/11.1/client/lib
./configure --with-pdo-oci=instantclient,/opt/oracle/instantclient,11.1
make
make install

Add the newly-built module to Apache:

chcon system_u:object_r:textrel_shlib_t:s0 /usr/lib/php/modules/pdo_oci.so
echo extension=pdo_oci.so > /etc/php.d/pdo_oci.ini
apachectl restart

The enhanced security under Fedora can sometimes interfere with Voyager communication. If things still aren't working after you have installed the modules and connected to Voyager by editing settings in /usr/local/vufind/web/conf/Voyager.ini, you may also need to repeat this command to unblock internal network communications:

setsebool -P httpd_can_network_relay=1

Regardless of the method you used to set up VuFind, you will need to follow these steps to configure final details and get the code running.

Some environment variables need to be set so that VuFind-related scripts can find Java and VuFind itself. If you plan on running VuFind under a specific user account, you should set these only for that user. If you want to make the settings global for all accounts (the easiest, but not necessarily the best, approach), just run this code to add the necessary lines to the /etc/profile file:

echo export JAVA_HOME=\"/usr/lib/jvm/java-openjdk\" >> /etc/profile
echo export VUFIND_HOME=\"/usr/local/vufind\"  >> /etc/profile

IMPORTANT: In some Fedora installations, the /usr/lib/jvm/java-openjdk directory will have version numbers embedded in it (i.e. /usr/lib/jvm/java-1.6.0-openjdk-1.6.0.0). You may need to adjust the lines above to account for this, or else you can create a symbolic link to create a virtual version-free directory:

ln -s /usr/lib/jvm/java-1.6.0-openjdk-1.6.0.0 /usr/lib/jvm/java-openjdk

After editing /etc/profile, you must reload it for the changes to take effect:

source /etc/profile

The software is installed, but you still need to configure it with things like your site's base URL and keys for various third-party services. Edit the /usr/local/vufind/web/conf/config.ini file to personalize VuFind for your library. The configuration file contains comments that should help you along the way.

You can use any text editor; if you are new to this, you might find Nano relatively easy (it's not beautiful, but at least the command reference is visible on the screen!):

nano /usr/local/vufind/web/conf/config.ini

To start VuFind:

cd /usr/local/vufind/
./vufind.sh start

For more information on managing the operation of the VuFind server, including how to make it start automatically, see the Starting and Stopping VuFind page.

VuFind won't do much good without any data – see the Importing Records page for more details on loading your content into the system.

Congratulations – you now have a running copy of VuFind. However, you should be aware of security concerns. See the Security page for some VuFind-specific notes, and take some time to learn about general issues in Unix security if you are not already familiar with the topic; LinuxSecurity.com is one good source for news and tutorials.