VuFind on Ubuntu

These instructions apply to VuFind 2.0 and newer; instructions for VuFind 1.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.

Version Requirements

These instructions were most recently tested on Ubuntu 17.04 but should also work with other recent versions with little or no modification. If you are using an older Ubuntu distribution, make sure it meets the requirements (such as minimum PHP version) of the VuFind release you are installing.

Getting Started

1. Install Ubuntu.

You can obtain a free copy of Ubuntu 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.

If you install a desktop version of Ubuntu, you will need to open the terminal application in order to run the commands listed below.

2. Update the system

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

sudoapt-get updatesudoapt-get dist-upgrade

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

sudo shutdown -r now

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. It will quickly load VuFind into the default /usr/local/vufind directory, making the assumption that your local settings belong in /usr/local/vufind/local.

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. Obtain the package

2. Install the package

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:

sudoapt-get install-f

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.

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, or at least make sure appropriate environment variable settings are loaded by 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. 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.

IMPORTANT: If your VuFind instance will include records with slashes in their IDs, you need to add “AllowEncodedSlashes on” to the appropriate <VirtualHost> section of your Apache configuration!

2. Install MySQL

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

sudoapt-get-yinstall 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

Note: Some Linux distributions have replaced MySQL with MariaDB. If you are working with one of those platforms (or if Ubuntu has changed its defaults by the time you are reading this), the two should be functionally equivalent.

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

Starting with VuFind 4.0, the php-mcrypt module is no longer needed. Instead, you will need the OpenSSL module, which should be automatically installed as part of the command above.

Note that the php5-ldap library is only needed if you will be using LDAP authentication; you can exclude this package 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:

sudoapt-get-yinstall php5-sybase

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

sudoapt-get-yinstall default-jdk

5. Download VuFind

All the prerequisites are in place, so now for the fun part – downloading and installing VuFind itself!

Instructions for obtaining VuFind can be found on the download page. You can either download a particular release in tar.gz or zip format, or you can load the latest development code directly from Git.

Starting with VuFind 3.0, when loading code from Git, you will also need to install dependencies using Composer.

You can choose whatever download method you prefer; here is a sample approach for downloading a pre-packaged .tar.gz file:

6. Install VuFind

The groundwork is set, so you can now run VuFind's install script to set up your basic configuration. You can accept the defaults for now – you can run the installer again later if you need to make changes.

cd/usr/local/vufind
php install.php

You should also set some permissions to allow Apache to write configuration and cache files to disk:

Note: making the cache world-writable is a simple but less-than-secure approach to enabling proper caching. You may wish to limit ownership to a specific VuFind CLI user or use ACL's using techniques described in Symfony's Installation Manual.

7. Link VuFind to Apache

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

8. 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 a new /etc/profile.d file:

Troubleshooting

If that does not help, try editing /usr/local/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).

There is a known issue in Ubuntu 13.10 that prevents the PHP mcrypt module from installing correctly. See this page for a workaround.

If you are still stuck, try one of the mailing lists on the 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 config.ini file.

After disabling auto configuration, you should also disable Apache's ability to write to your configuration directory:

sudo chown -R root:root /usr/local/vufind/local/config

(Replace “root:root” with a different user/group if you have set up a particular Linux user for the purposes of running VuFind; replace /usr/local/vufind with your VuFind base path if you have customized the location of your installation).

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.