This is an old revision of the document!
Table of Contents
VuFind® on Ubuntu
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 22.04 LTS and Debian 10.1 but should also work with other recent versions with little or no modification. Use of an LTS (long term support) release is strongly recommended to reduce the amount of upgrading you will need to do over time. 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.
sudo apt-get update sudo apt-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
wget https://github.com/vufind-org/vufind/releases/download/v10.0/vufind_10.0.deb
2. Install preferred dependencies (optional)
By default, if your system does not already have PHP, Java or a MySQL-compatible database installed, VuFind®'s .deb package will automatically install these for you. VuFind® picks your distribution's default PHP version and Java JDK (usually JDK 11 as of this writing) and will choose MySQL over MariaDB (if both options are available in the distribution). If you have different preferences, you can install alternative compatible packages before installing the VuFind® package, and it should take advantage of them instead of installing unwanted versions.
Example 1: Installing a Non-Default JDK
This option is not supported before VuFind® 7.1, which increased the flexibility of Java handling in the .deb package.
If you want to run VuFind® with JDK 17 in an Ubuntu release that uses JDK 11 by default, you can simply run: sudo apt-get install openjdk-17-jdk
prior to installing the .deb package.
Example 2: Using MariaDB instead of MySQL
If you prefer MariaDB to MySQL, simply run this command before installing VuFind®: sudo apt-get install mariadb-server
3. Install the package
sudo dpkg -i vufind_10.0.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
Important Notes
Database Issues
- Case 1 - MySQL: If you wish to connect to the root account through the web-based installer in order to set up VuFind®'s database, you should follow these steps:
- Disable the root account's “auth_socket” plugin, which prevents regular logins, by logging in with
sudo mysql -uroot
and then runningUPDATE mysql.user SET plugin='mysql_native_password' WHERE User='root'; FLUSH PRIVILEGES;
- Quit the MySQL tool and run
sudo /usr/bin/mysql_secure_installation
at the command line to automatically improve some database security settings. - If the mysql_secure_installation process does not automatically help you set a root password, you may wish to do so manually, by logging in with
sudo mysql -uroot
and then runningALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password by 'your-password-here';
- Edit /etc/mysql/mysql.conf.d/mysqld.cnf, add the appropriate line for your Ubuntu version to the bottom of the file:
- Ubuntu 20/21: default_authentication_plugin=mysql_native_password
- Ubuntu 22+: authentication_policy=mysql_native_password
- Run
sudo service mysql restart
before attempting to set up VuFind®. This will ensure that new accounts are created using a PHP-compatible authentication method.
- Case 2 - MariaDB 10.3 and earlier: If you are using a distribution that includes MariaDB instead of MySQL, you will not be prompted to set a root password during installation. Instead, you should run
sudo /usr/bin/mysql_secure_installation
to properly set up security. If this command is missing, try installing the mariadb-client and mariadb-server packages with apt-get. If you wish to connect to the root account through the web-based installer in order to set up VuFind®'s database, you may also need to disable the root account's “unix_socket” plugin, which prevents regular logins. You can do this by logging in withsudo mysql -uroot -p
and then runningUPDATE mysql.user SET plugin='' WHERE User='root'; FLUSH PRIVILEGES;
- Case 3 - MariaDB 10.4 and later: MariaDB 10.4 significantly changes how authentication is handled; see Authentication from MariaDB 10.4 in the application's documentation for more details. Notes on successfully configuring MariaDB 10.4 and VuFind® will be added here as time permits.
- When all else fails: If you cannot successfully connect to the database with VuFind®'s installer using the root account, you can still set up the database manually through the command line. When filling out the “Auto Configure” database form, omit the “MySQL Root User” and “MySQL Root Password” fields at the bottom, and instead of clicking the regular “Submit” form, click the “Skip” button below it. This will show you all of the SQL commands that need to be run to set up VuFind®'s database. Using the MySQL command line client (
mysql -u root -p
), run the first four (CREATE DATABASE/CREATE USER/GRANT/FLUSH) commands that are displayed. This will set up your new VuFind® database. Now, you need to run a “USE” command to select that database (e.g. “USE vufind;” if you're using the default database name of “vufind”). Finally, copy and paste the remainder of the SQL (consisting of many CREATE TABLE statements). This will populate your new VuFind® database. You may also need to edit the [Database] section of config.ini to adjust the database connection string to use the credentials created for your new database.
Encryption Issues
If you are using Ubuntu 22.04 or newer, OpenSSL may not be configured to support VuFind®'s default blowfish encryption algorithm, which could lead to errors when users access their ILS accounts. VuFind® 9.0 and newer should automatically help you solve this problem through the installation/upgrade process, but for earlier releases, see VUFIND-1563 for a workaround.
ILS-Specific Issues
- If you are a Voyager library, you will also need to install the PHP OCI Driver for Oracle.
- If you will be accessing a Sybase database (e.g. for the Horizon LMS), you should also install the php-sybase package using apt-get.
Rolling Back
- 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:
source /etc/profile
Now 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. 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
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:
sudo apt-get -y install mysql-server
Note: See Database Issues above for some important notes on additional setup that may be necessary to make the database compatible with VuFind®.
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. The two should be functionally equivalent, and both should work equally well with VuFind®.
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.)
sudo apt-get -y install libapache2-mod-php php-mbstring php-pear php php-dev php-gd php-intl php-json php-ldap php-mysql php-xml php-soap php-curl
Note that the php-ldap library is only needed if you will be using LDAP authentication; you can exclude this package if you like. The php-soap library is only used by the Symphony ILS driver (as of this writing), but it is required by one of VuFind®'s composer dependencies and will need to be installed if you plan to run composer manually for any reason. 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 this page for detailed instructions.
If you will be accessing a Sybase database (e.g. for the Horizon LMS), also install php-sybase:
sudo apt-get -y install php-sybase
These instructions assume you are using an Ubuntu distribution including PHP 7. If you are on an older distribution, you may need to change “php” to “php5” in the package names and install a PHP 5-compatible version of VuFind® (4.x or earlier). This is not recommended!
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.
sudo apt-get -y install 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:
cd /tmp wget https://github.com/vufind-org/vufind/releases/download/v10.0/vufind-10.0.tar.gz tar -xzvf vufind-10.0.tar.gz sudo mv vufind-10.0 /usr/local/vufind
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:
sudo chown -R www-data:www-data /usr/local/vufind/local/cache sudo chown -R www-data:www-data /usr/local/vufind/local/config
If you plan to use VuFind®'s command line tools, you also need a separate cache for that:
sudo mkdir /usr/local/vufind/local/cache/cli sudo chmod 777 /usr/local/vufind/local/cache/cli
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:
Apache 2.2 (Ubuntu 13.04 or earlier):
sudo ln -s /usr/local/vufind/local/httpd-vufind.conf /etc/apache2/conf.d/vufind
Apache 2.4 (Ubuntu 13.10 or later):
sudo ln -s /usr/local/vufind/local/httpd-vufind.conf /etc/apache2/conf-enabled/vufind.conf
Apache needs to be restarted so the changes can take effect:
sudo /etc/init.d/apache2 reload
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:
sudo sh -c 'echo export JAVA_HOME=\"/usr/lib/jvm/default-java\" > /etc/profile.d/vufind.sh' sudo sh -c 'echo export VUFIND_HOME=\"/usr/local/vufind\" >> /etc/profile.d/vufind.sh' sudo sh -c 'echo export VUFIND_LOCAL_DIR=\"/usr/local/vufind/local\" >> /etc/profile.d/vufind.sh'
Note: If you have multiple JVMs and want to use a non-default one instead, you may need to specify a different JAVA_HOME path, like /usr/lib/jvm/java-17-openjdk-amd64.
After creating the file, you must load it manually for the changes to take effect without forcing you to log out and back in again:
source /etc/profile.d/vufind.sh
9. 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. Start Solr
To start VuFind®'s Solr index:
cd /usr/local/vufind/ ./solr.sh start
If you get a warning about limit settings, see the starting and stopping Solr page for details on how to fix it.
For more information on managing the operation of the VuFind® server, including troubleshooting notes and instructions for starting it automatically, see the Starting and Stopping Solr page.
2. Configure VuFind®
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.
The troubleshooting page has several suggestions that may help.
If you are still stuck, try one of the mailing lists on the support page; the community is always willing to help new arrivals.
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.
If you have trouble setting up the database, see database issues above for suggestions.
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 and Prepare for Production
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.
Do not forget this step before going into production – an improperly secured system on the open Internet can quickly come under attack.
There are also some further production-specific considerations listed in the Production Checklist.