About Features Downloads Getting Started Documentation Events Support

Site Tools


legacy:installation:ubuntu

VuFind 1.4 on Ubuntu

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

Instructions for VuFind 2.x can be found here.

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.

Getting Started

Install Ubuntu. These instructions were originally written with Ubuntu Server Edition 10.04 LTS in mind, but they should also work on other versions with little or no modification. They have most recently been tested with version 12.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.

Installing VuFind from the DEB Package

The easiest way to get VuFind up and running is to install it from the DEB package. This section provides instructions on doing that. If you want more control over the installation, skip down to the Detailed Installation Instructions to install everything manually and read explanations of each step of the process.

1. Update the system

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

sudo apt-get dist-upgrade

If the dist-upgrade doesn't produce any results, you might want to try this command first:

sudo apt-get update

After installing patches, you should probably reboot your system so that everything can take effect:

sudo shutdown -r now

2. Install the DEB Package

First, obtain the package from our download site:

wget http://downloads.sourceforge.net/vufind/vufind_1.4.deb?use_mirror=osdn -O vufind_1.4.deb

Next, install the package using the dpkg utility:

sudo dpkg -i vufind_1.4.deb

If you do not have all of VuFind's dependencies installed already, dpkg will fail with an error message. You can correct this problem by installing the missing requirements using apt-get:

sudo apt-get install -f

If this fails to install everything you need, you may also want to try installing packages individually like this:

sudo apt-get install [package from dpkg error message]

If necessary, repeat the process of attempting a dpkg installation and installing missing dependencies with apt-get until dpkg is successful. You will know the installation was successful because you will be prompted for database information by VuFind's installation script.

Some important notes:

  • If you need to install MySQL, you will be prompted for a root password during installation. 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.
  • If you are a Voyager library, you will also need to install the PHP OCI Driver for Oracle – see this page for detailed instructions.
  • If you will be accessing a Sybase database (e.g. for the Horizon LMS), you should also install the php5-sybase package using apt-get.
  • You will need to answer some prompts during the installation process. If you use a graphical package manager rather than the command line tool, you may not be able to see these prompts unless you open a Terminal window. For this reason, it is recommended that you use the command line method as described above.
  • You may see some minor errors and warnings while everything gets set up – this is normal, so don't panic!
  • If, for some reason, you need to remove the package, you can issue this command (note that -P is for purge and will remove configuration files as well as executable components; use -r for a more cautious removal): sudo dpkg -P vufind

Once everything is set up, you should have a working copy of VuFind in /usr/local/vufind. You may want to restart your system one more time to be sure all the new settings are in place, then you can proceed to Configuring and Starting VuFind below to finish setup and get things running!

Detailed Installation Instructions

Following these steps will give you a running instance of VuFind. Note that if you already followed the steps above to install VuFind from the DEB package, you can skip this entire section!

1. Update the system

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

sudo apt-get dist-upgrade

After installing patches, you should probably reboot your system so that everything can take effect:

sudo shutdown -r now

2. Install Apache HTTP Server

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

3. Install MySQL

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.

Note: If you would like to do web-based administration of your database, you may also find it helpful to install the phpmyadmin tool: sudo apt-get install phpmyadmin

4. Install PHP

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 php5-gd

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. The php5-gd package is also optional, though including it will ensure better support for cover images. PHP's mbstring library is strongly recommended, but as of this writing, it appears to be automatically included in the php5-dev package.

If you are a Voyager library, you will also need to install the PHP OCI Driver for Oracle – see this page 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

5. Install the Java JDK

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

sudo apt-get -y install default-jdk

Note: These instructions used to recommend using the Sun JDK (package: sun-java6-jdk) rather than the default. However, sun-java6-jdk is harder to install in Ubuntu 10.x and higher, and the default JDK seems to work just as well.

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.

6. Download VuFind

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
svn export --force https://vufind.svn.sourceforge.net/svnroot/vufind/releases/VuFind-1.4 /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

8. Install VuFind

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

9. Set Up Environment Variables

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/default-java\" >> /etc/profile'
sudo sh -c 'echo export VUFIND_HOME=\"/usr/local/vufind\"  >> /etc/profile'

Note: If you are using the Sun JVM instead of the default JVM, your JAVA_HOME path should actually be /usr/lib/jvm/java-6-sun.

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

source /etc/profile

10. Final Configuration

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

Configuring and Starting VuFind

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.

1. Configure VuFind

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

If you used a non-standard install directory (not /usr/local/vufind), you should also edit import/import.properties to adjust paths. If you plan to load authority records, the same thing needs to be done in import/import_auth.properties.

2. Start VuFind

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

3. Import Records

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

4. Secure Your 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.

5. Mail Issues

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

pear install Mail-1.2.ob2
pear install Net_SMTP
legacy/installation/ubuntu.txt · Last modified: 2015/12/14 14:50 by demiankatz