====== VuFind 1.3 on Fedora ======
//This documentation will help you install VuFind 1.3. Documentation for the previous major release, VuFind 1.2, can be found [[http://vufind.org/wiki/installation_fedora?rev=1312203999|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.
====== Getting Started ======
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 [[http://fedoraproject.org/|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 [[http://fedoraproject.org/en/get-fedora-options#formats|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 [[installation_fedora#a_mostly_scripted_default_installation|A (Mostly) Scripted Default Installation]] for the automated process. Continue reading [[installation_fedora#detailed_installation_instructions|Detailed Installation Instructions]] to install manually and read explanations of each step of the process.//
====== A Note on SELinux ======
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 [[http://www.lfymag.com/admin/issuepdf/SELinux%20primer.pdf|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.
====== Detailed Installation Instructions ======
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!
===== 1. Update the system =====
The first step is to make sure you have the latest patches installed.
yum update
===== 2. Install Apache HTTP Server =====
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
===== 3. Install MySQL =====
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
===== 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.)
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 [[installation_fedora#php_oci_driver_for_oracle|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
===== 5. Install the Java JDK =====
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.//
===== 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:
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/*
===== 7. Link VuFind to Apache =====
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
==== Alternate Approach ====
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.
===== 8. Install WGET =====
The VuFind install process needs the wget command to download components; make sure it is available:
yum install wget
===== 9. 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
/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/*
===== 10. Final Configuration =====
Everything is set up - proceed to [[installation_fedora#configuring_and_starting_vufind|Configuring and Starting VuFind]] below.
====== A (Mostly) Scripted Default Installation ======
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 [[installation_fedora#php_oci_driver_for_oracle|PHP OCI Driver for Oracle]] - see the section below for detailed instructions.
After running the script, proceed to [[installation_fedora#configuring_and_starting_vufind|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/*
====== PHP OCI Driver for Oracle ======
There are a few steps if you need to install the OCI8 libraries.
===== 1. Upgrade PEAR =====
First, upgrade pear to the latest version (this won't do anything if you are already up to date).
pear upgrade pear
===== 2. Download and Extract the Oracle Instant Client =====
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 [[http://www.oracle.com/technology/software/tech/oci/instantclient/index.html|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
===== 3. Install the Client and PHP Extension =====
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
===== 4. Set up PDO_OCI =====
If VuFind doesn't work for you with just the OCI8 package installed, you may also need PDO_OCI. (Notes adapted from [[http://ubuntuforums.org/showthread.php?p=7581997|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
===== 5. Reaffirm Security Settings =====
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
====== 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. 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:
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
===== 2. 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!):
nano /usr/local/vufind/web/conf/config.ini
===== 3. 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 VuFind]] page.
===== 4. Import Records =====
VuFind won't do much good without any data – see the [[Importing Records]] page for more details on loading your content into the system.
===== 5. 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; [[http://www.linuxsecurity.com/|LinuxSecurity.com]] is one good source for news and tutorials.