you're reading...


Fez Installation and Configuration Guide

This guide is geared towards helping novice users setup Fez which is a front-end to Fedora commons. This guide contains easy steps which helps users go through various steps without much hassle. The guide makes assumption that the user is running either Fedora Linux or a compatible GNU/Linux distribution (e.g. RHEL, CentOS). Even though, with a few changes, the installation can be performed under other Linux distributions. All the commands should be run as an authenticated user, either as “root” or with “sudo”.


  • [Square braces] are used to denote keystrokes.
  • “Quotes” are used to denote values and keywords.


Fez is an open source project to produce and maintain a highly flexible web interface to FEDORA for any Library or Institution to configure and publish or archive documents of any type sustainably. Fez is a PHP / MySQL front end to the Fedora repository software. It is developed by the University of Queensland Library as an open source project hosted on SourceForge.

Install Prerequisites

Apache Web Server

yum install httpd


yum install php php-devel php-gd php-mysql php-pgsql php-xml

MySQL Database Server

yum install mysql mysql-server libdbi-dbd-mysql mysql-connector-odbc mysql-devel

Other image manipulation tools

yum install ImageMagick poppler poppler-utils libpng-devel

Additional Libraries (php-tidy & libtidy)

yum install libtidy php-tidy


yum install graphviz

To correctly run graphviz, execute:

dot -c


yum install perl-Image-ExifTool

Fedora Commons

See the installation instructions.


JHOVE (JSTOR/Harvard Object Validation Environment) – pronounced “jove” – is a joint project of JSTOR and the Harvard University Library to develop an extensible framework for format validation. JHOVE is a format-specific digital object validation API written in Java.

Obtaining JHOVE

Download JHOVE’s recent distribution from http://sourceforge.net/project/showfiles.php?group_id=221311. At the time of writing this guide, the recent distribution is version 1.4 and the direct download link is http://sourceforge.net/projects/jhove/files/jhove/JHOVE%201.4/jhove-1_4.tar.gz/download.
To download JHOVE v1.4, execute:

wget http://sourceforge.net/projects/jhove/files/jhove/JHOVE%201.4/jhove-1_4.tar.gz/download

Installing JHOVE

  • Extract JHOVE tarball (jhove-*.tar.gz).
    tar -zxvf jhove-*.tar.gz

    This should extract the jhove tarball and create a directory called “jhove” at the current location.

  • JHOVE installation base directory (the jhove directory that we have just created by extracting in the previous step), should be copied to “/usr/local/src/”.
cp -av jhove/ /usr/local/src/

Configuring JHOVE

  • Download “jhoveConfig.xsd” file and place it to your apache’s DocumentRoot directory (i.e. /var/www/html/).
wget hul.harvard.edu/ois/xml/xsd/jhove/jhoveConfig.xsd
mv jhoveConfig.xsd /var/www/html/
chmod 755 /var/www/html/jhoveConfig.xsd
chown apache:apache /var/www/html/jhoveConfig.xsd
chcon --reference=/var/www/html/ /var/www/html/jhoveConfig.xsd
  • Change your directory to JHOVE’s installation directory.
    cd /usr/local/src/jhove/
  • Edit the JHOVE’s configuration file. Open the file “conf/jhove.conf” in a file editor.
    vim conf/jhove.conf
  • Replace the line “<jhoveHome>/users/stephen/projects/jhove</jhoveHome>” with “<jhoveHome>/usr/local/src/jhove/</jhoveHome>”.
  • Replace the line “<tempDirectory>/var/tmp</tempDirectory>” with “<tempDirectory>/tmp</tempDirectory>”.
  • Replace the line xsi:schemaLocation=”http://hul.harvard.edu/ois/xml/ns/jhove/jhoveConfig
    with xsi:schemaLocation=”http://hul.harvard.edu/ois/xml/ns/jhove/jhoveConfig http://localhost/jhoveConfig.xsd”>
  • Save the file and exit the editor.
  • Edit the JHOVE’s shell script. Open the file “jhove” in a file editor.
    vim jhove
  • Replace the line “JHOVE_HOME=[fill in path to jhove directory]” with “JHOVE_HOME=/usr/local/src/jhove/”.
  • Replace the line “JAVA_HOME=/usr/java” with “JAVA_HOME=/opt/jdk1.6.0_17/”. Note, we are assuming that we have installed Sun JDK at /opt/jdk1.6.0_17/. If you have a different location for Sun JDK installation, use the path of that directory in this step.
  • Replace the line “${JAVA} -classpath $CP Jhove $ARGS” with “${JAVA} -classpath $CP Jhove -c ${JHOVE_HOME}/conf/jhove.conf $ARGS”.
  • Save the file and exit the editor.
  • Set proper file permissions.
chmod -R 755 /usr/local/src/jhove/
  • Change your directory to /usr/local/.
    cd /usr/local/
  • Make a symbolic link to the jhove installation directory here.
    ln -s /usr/local/src/jhove/

Prepare Environment Variables

  • JHOVE_HOME: This variable should point out to the jhove installation base directory.
  • PATH: This variable should include the path to the jhove installation base directory so that the jhove script could be run without pointing out the absolute path.

To prepare these variables we would add the instruction in the file /etc/profile.d/fedora-profile.sh. Remember that we have used the same file while installing and configuring fedora.

  • Edit the file /etc/profile.d/fedora-profile.sh. Open the file in an editor.
    vim /etc/profile.d/fedora-profile.sh
  • Add/Edit these lines:

Remember not to delete other lines in the file. Also the last statement should include other variables like CLASSPATH JAVA_HOME etc.

  • Save the file and exit the editor.

Configure MySQL

  • Edit /etc/my.cnf and add the following in the [mysqld] section:
# Fez customization
  • Check is MySQl service is running:
service mysqld status
  • If it is not running, start it:
service mysqld start
  • If MySQL service is already running, you need to restart the service:
service mysqld restart
  • To make mysql run at every startup:
chkconfig mysqld on
  • Login to MySQL.
mysql -u root -p

Type the password for the MySQL root user and press [Enter].

  • Create a database for fez. At the mysql prompt, execute:
CREATE DATABASE fez default charset utf8;
  • Create a user for fez and assign all privileges to the user on the fez database.
GRANT ALL ON fez.* TO fezuser@localhost IDENTIFIED BY 'userfez';
FLUSH privileges;

Note: Use your own password instead of “userfez”.

  • Exit MySQL prompt.

Obtaining Fez

You can download the installation bundle of Fez at Fez’s page at Sourceforge – http://sourceforge.net/projects/fez/. The recent bundle at the time of writing this guide is version 2.1RC3. The direct link to the download of version 2.1RC3 is http://sourceforge.net/projects/fez/files/Fez/Fez%202.1%20RC3/fez-2.1_rc3.tar.gz/download.
To download the 2.1RC3 bundle, execute:

wget http://sourceforge.net/projects/fez/files/Fez/Fez%202.1%20RC3/fez-2.1_rc3.tar.gz/download

Installing Fez

  • Extract the Fez installation tarball (fez-*.tar.gz).
tar -zxvf fez-*.tar.gz

This should create a directory call fez-2.1_rc3 (if you are using version 2.1RC3).

  • Move the Fez directory to Apache’s DocumentRoot (i.e. /var/www/html/).
mv fez-2.1_rc3/ /var/www/html/fez/

Note: Here we are renaming the directory to “fez” while moving.

  • Create a file called error_handler.log inside the fez installation directory.
touch /var/www/html/fez/error_handler.log
  • Create an “incoming” directory inside fez installation directory.
mkdir -p /var/www/html/fez/incoming/
  • Create an “duplicates_reports” directory inside fez installation directory.
mkdir -p /var/www/html/fez/duplicates_reports/
  • Change permissions on the directory.
chmod -R 755 /var/www/html/fez/
chown -R apache:apache /var/www/html/fez/
chcon -R --reference=/var/www/html /var/www/html/fez/
  • Start/Restart Apache service.

Note: Ensure that proper SELinux settings are made or SELinux is set into permissive mode, else the page would not be displayed, and you will get a Apache’s permission error page.

  • Open a browser and point at http://localhost/fez/. This should open the fez installation page. Click on the “Proceed to the first step” button.
  • The next page would ask you about “Core Settings”.
  • Keep the “Application path” at “/var/www/html/fez/” which is also the default option.
  • Set the “Relative path” to “/fez/”.
  • Choose “Database type” as “MySQL”.
  • Set “Database host” to “localhost”.
  • Set “Database name” to “fez”. Remember to use a different name if you have created a different database for fez in the section “Configuring MySQL”.
  • Set “Database username” to “fezuser”.
  • Set “Database password” to “userfez”.
  • Click on “Proceed to next step” button.
  • At this step you shall see an alert box saying “Please allow a couple of minutes for the next step to be performed. Do not refresh the next page during this time.”. Click on the “OK” button.
  • The next stage/page will show you if your installation was successful or not. Typically, the first line on the page should say “Success!”. If the installation was successful, you need to delete the setup directory.
rm -Rf /var/www/html/fez/setup/

Configuring Apache for Fez

  • Create a apache configuration file for fez.
touch /etc/httpd/conf.d/fez.conf
  • Edit the configuration file.
vim /etc/httpd/conf.d/fez.conf
  • Add the following lines to the file:
Alias /fez /var/www/html/fez/

<Directory "/var/www/html/fez/">
	Options Indexes FollowSymLinks
	AllowOverride All
	Order Allow,Deny
	Allow from All
  • Save the file and exit the editor.
  • Open php.ini to tweak a few settings.
vim /etc/php.ini
  • Set upload_max_filesize to 10MB. This sets the limit of the maximum file size for upload to be 10 MB rather than the default 2MB.
upload_max_filesize = 10M
  • Set post_max_filesize to 10MB.
post_max_size = 10M
  • Save file and exit the editor.
  • Restart Apache (httpd service).

Configuring Fez

  • Ensure Fedora service is running.
  • Point your browser to http://localhost/fez/. If your browser shows you a lot of warnings related to PHP saying “Warning: Call-time pass-by-reference has been deprecated …”, this means that the version of PHP you are running on your machine has deprecated one of the feature called “Call-time pass-by-reference” and you need to make some changes to stop the warning from being displayed. You need to set the “error_reporting” to “E_ERROR”. To change the error reporting level:
sed -i -e 's/E_ALL ^ E_NOTICE/E_ERROR/' /var/www/html/fez/config.inc.php

Now refresh the fez startup page, it should not show you that error again.

  • Click on the login link to open the login page. Use these credentials (the default username and password) to log in:
username: admin
password: admin
  • After successfully logging in, you should see the “Administration” link in the top left corner of the page. Click on the link.
  • Now you are directed to the Configuration page where you can see a lot of configuration options. On the left pane, click on the “Site Configuration” link. This should open the site configuration settings on the right pane.
  • Click on the “General Settings” link.
  • Set the “Application Name” to an appropriate name like “Pustakalaya”.
  • Set the “Admin Email” to a valid email address.
  • Set the “Organization Name” to an appropriate name.
  • Set the “Short org. Name” to the short form of the organization’s name.
  • Set the “Hostname” to “localhost” if you are testing fez, else set it to an appropriate DNS resolvable hostname, or the IP address.
  • Set the “SMTP Server” to an appropriate SMTP server’s address(name or IP) which the application should use while sending emails.
  • Set the “System email from address” to an appropriate and valid email address. Fez will use that address as a value for the field “FROM” email address while sending mails.
  • Set other options as per your choice.
  • Click on the “Save Changes” button.
  • Next, click on the “Fedora Settings” link. Remember, much of the settings come from the previous stage where we installed Fedora Commons. Refer to those settings.
  • Set “Version” to 2.2 or 2.2.1, which is also the default option.
  • Set “Location” to localhost:8080/fedora.
  • Set “Server Setup” to no-ssl-authenticate-all.
  • Set “PID namespace” to Pustakalaya or the PID Namespace that you have used which configuring Fedora.
  • Set “Username” to the Fedora Commons username (i.e. fedoraAdmin).
  • Set “Password” to Fedora Commons Password (i.e. adminFedora).
  • Set “Database Name” to fedora22.
  • Set “Database Username” to adminFedora.
  • Set “Database password” to adminFedora.
  • Click on the “Save Changes” button.
  • Next, click on the “Programs and Paths” link.
  • Set the “SAN import directory” to /var/www/html/fez/incoming/.
  • Set “Duplicate reports directory” to /var/www/html/fez/duplicates_reports/.
  • Set “Graphviz DOT executable location” to /usr/bin/dot.
  • Set “PHP executable location” to /usr/bin/php.
  • Click on the “Save Changes” button.

You can choose to configure other options as well. In this example installation we would not change other stuffs. After you are done with the configuration and saved them, Click on the “Sanity Checks” link. This shall open a new tab/window. It will check fez installation and report if there are any problems.
If the sanity test reports error like:

Failed:  ConnectHTTP  APP_BASE_FEDORA_APIM_DOMAIN   = 'http://fedoraAdmin:adminFedora@localhost:8080/fedora'  HTTP Result 401 code.

then you have to edit a file at /var/www/html/fez/includes/class.sanity_checks.php

  • Open that file in a text editor.
vim /var/www/html/fez/includes/class.sanity_checks.php
  • Exit the editor.

All the errors are self explanatory, read them carefully to find out problems with your installation and finally fix them.

Now you are ready to use a full fledged repository based online Library.


2 Responses to “Fez Installation and Configuration Guide”

  1. Hi Aks!
    The guide is Very Good!
    Have you tried to install FEZ with newer versions of FEDORA?


    Posted by Aris Polizos | May 9, 2011, 10:28 am
    • Aris,
      I’ve not tried with the recent version but am planning to test. I assume the installation of new version of both the software should be the similar (to that discussed). Let me know if you want anything specific with the new version or the installation.

      Posted by Abhishek Singh | May 9, 2011, 10:30 am

Post a Comment