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

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

Install Ubuntu. These instructions were written with Ubuntu Server Edition 8.04 LTS in mind. They should also work with versions 9.04 and 9.10. You can obtain a free copy of the software and find installation instructions at www.ubuntu.com. You do not need to install any special packages during the install process to get VuFind working.

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

Following these steps will give you a running instance of VuFind.

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

sudo apt-get dist-upgrade

Now install the Apache web server. This will facilitate communication between VuFind and web browsers. The following lines accomplish three things: the first line installs Apache, the second line turns on the URL rewriting module required by VuFind, and the third line restarts the server to activate the newly-installed module.

sudo apt-get -y install apache2
sudo a2enmod rewrite
sudo /etc/init.d/apache2 force-reload

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

sudo apt-get -y install mysql-server

Note: During installation, you will be prompted for a MySQL root password. For better security, it is a good idea to set this; if you do, be sure you remember it so you can configure VuFind to access the database later.

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

sudo apt-get -y install php5 php5-dev php-pear php5-ldap php5-mysql php5-xsl php5-pspell

Note that the php5-ldap library is only needed if you will be using LDAP authentication, and the php5-pspell library is not used at all but might feature in future spelling-related enhancements; you can exclude these packages if you like.

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 php5-sybase:

sudo apt-get -y install php5-sybase

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

sudo apt-get -y install sun-java6-jdk

While you're installing Java, you'll be prompted to accept the user license.

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:

sudo apt-get install subversion
sudo svn export --force https://vufind.svn.sourceforge.net/svnroot/vufind/releases/VuFind-1.0RC2 /tmp/vf_download
sudo mv /tmp/vf_download /usr/local/vufind

Note that we download VuFind to the tmp directory and then move it into place as a second step – this prevents it from being loaded with “root” ownership, which can cause permission problems.

If you prefer not to use Subversion, you can also download the software from the downloads page and unpack it manually.

Apache needs to have write access to some of the VuFind subdirectories – these commands set that up:

sudo chown www-data:www-data /usr/local/vufind/web/interface/compile
sudo chown www-data:www-data /usr/local/vufind/web/interface/cache 
sudo chown www-data:www-data /usr/local/vufind/web/images/covers/*

Apache needs to have some extra VuFind settings loaded. Run this command to make Apache aware of VuFind's configuration file:

sudo ln -s /usr/local/vufind/httpd-vufind.conf /etc/apache2/conf.d/vufind

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

sudo /etc/init.d/apache2 reload

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
sudo /usr/local/vufind/install

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

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

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 Ubuntu. Just save this script as ubuntu_setup.sh. IF YOU ALREADY FOLLOWED THE STEP-BY-STEP INSTRUCTIONS ABOVE, YOU CAN SKIP THIS – IT DOES THE SAME THING!

sudo sh ubuntu_setup.sh

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.0RC2 on Ubuntu
# This does not include the OCI8 libraries
 
# Set some variables
VUFIND_SVN="https://vufind.svn.sourceforge.net/svnroot/vufind/releases/VuFind-1.0RC2"
VUFIND_HOME="/usr/local/vufind"
 
# Update the system and install software
sudo apt-get dist-upgrade
sudo apt-get -y install sun-java6-jdk apache2 php5 php5-dev php-pear php5-ldap php5-mysql php5-xsl php5-pspell mysql-server
 
# enable mod_rewrite
sudo a2enmod rewrite
 
# download VuFind using Subversion
sudo apt-get -y install subversion
svn export --force $VUFIND_SVN /tmp/vf_download
sudo mv /tmp/vf_download $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 write to certain directories.
sudo chown www-data:www-data $VUFIND_HOME/web/interface/compile
sudo chown www-data:www-data $VUFIND_HOME/web/interface/cache
sudo chown www-data:www-data $VUFIND_HOME/web/images/covers/*
 
# set up Apache for VuFind and reload configuration
sudo ln -s $VUFIND_HOME/httpd-vufind.conf /etc/apache2/conf.d/vufind
sudo /etc/init.d/apache2 force-reload
 
# Finalize the installation 
cd $VUFIND_HOME
sudo $VUFIND_HOME/install
sudo chmod +x $VUFIND_HOME/vufind.sh
sudo chmod +x $VUFIND_HOME/import-marc.sh

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

First, upgrade pear to the latest version1).

sudo pear upgrade pear

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

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

Install the unzip utility (for extracting files from the archives) if you haven't already:

sudo apt-get install unzip

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

sudo unzip basic.zip
sudo unzip sdk.zip

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

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

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

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

sudo sh -c 'echo /opt/oracle/instantclient > /etc/ld.so.conf.d/oracle-instantclient'

You will need the make utility if you do not already have it. Install it like this:

sudo apt-get install make

Now compile and install the OCI8 package with PECL

sudo 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

sudo sh -c 'echo extension=oci8.so >> /etc/php5/apache2/php.ini'
sudo /etc/init.d/apache2 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).

Install some prerequisites:

sudo apt-get install --yes build-essential libaio1

Download and unzip the package:

sudo mkdir -p /tmp/pear/download/
cd /tmp/pear/download/
sudo pecl download pdo_oci
sudo 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:

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

Add the newly-built module to Apache:

sudo sh -c 'echo extension=pdo_oci.so >> /etc/php5/apache2/php.ini'
sudo /etc/init.d/apache2 restart

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:

sudo sh -c 'echo export JAVA_HOME=\"/usr/lib/jvm/java-6-sun\" >> /etc/profile'
sudo sh -c 'echo export VUFIND_HOME=\"/usr/local/vufind\"  >> /etc/profile'

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

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

If you are unable to use “text this” and “email this” try installing:

pear install Mail-1.2.ob2
pear install Net_SMTP