Installation / Quick Start Guide

Software Release Information

Software: Fez
Release Number: 1.2.0 BETA
Release Date: Not released yet
Support: For more information or support, please join the fez users email list at http://lists.sourceforge.net/lists/listinfo/fez-users

Introduction

This document describes how to install and get started with Fez.

Minimal System Requirements

System requirements are described in the release notes.

Installation

What other software must be installed first?
Fez has been tested successfully on Windows, Linux and Apple OS/X operating systems. Before you can install this product, you must install the following packages. This can all be installed on the one server, or separate servers for mysql, apache, fedora if you wish.
  • Fedora 2.1.1 Digital Repository
    • Note: You can also use Fedora 2.0 instead by modfying the Fez generated config.inc.php by commenting out the 2.1 API-M and API-A soap locations and uncommenting the 2.0 locations (2 lines each). This is due to the fact the API soap locations were changed from 2.0 to 2.1.
    • IMPORTANT: Make sure that whatever PID prefix namespace you choose is also in the "retainPIDS" set of namespaces. Eg if your PID namespace is "UQ" make sure "UQ" is in the list of retainPIDS in fedora.fcfg. If this is not set then Fez will not be able to create objects in Fedora.

    • Recommendations:
      • Fez uses its own security engine (FezACML) so suggest setting the Fedora XACML it to "permit-all-requests" (turns it off) as this will increase Fez/Fedora performance. With this setting Fedora still requires authentication for the API-M, but we strongly suggest you firewall the Fedora server to allow access to port 8080 (Fedora tomcat port) to only the Fez webserver. If you do not experience noticable performance degradation with XACML set to "enforce-policies" (turned on) we still reccommend firewalling the Fedora server for added security.
      • Since Fez has its own "index" for searching through Fedora we suggest turning off the Fedora Kowari index as this will improve Fedora performance. Fez only requires the Kowari resource index to be turned on if you wish to reindex Fedora objects back into Fez. If you try to re-index fedora objects into Fez with the Kowari index turned off Fez will give you an error instructing you on how to turn it back on (if temporarily). This is able to be set in the Fedora fedora.fcfg file by setting resourceIndex to 0 for off, 1 for on.
  • Java SDK
    • Notes:
      • The Java SDK 1.4.2 is required by Fedora and JHOVE (for the JRE). Setup the JAVA_HOME, FEDORA_HOME and other environment variables as per the Fedora installation instructions. According to the Fedora mailing list there are problems with using Java version 1.5, so it is preferable to use version 1.4.2.
  • Apache Web Server
    • Notes:
      • We have only tested using Apache 1.3.x on linux (Apache 1.3.x or 2.x on Windows XP is fine), however there should be no reason Fez won't run on Apache 2.x. Fez should also be able to run on any webserver that will support PHP5 (eg Microsoft IIS etc) but we have not tested this yet.
      • We recommend setting apache to recognise "index.php" as a "Directory Index" so that the Fez index file is loaded immediately eg:
        • <IfModule mod_dir.c>
          DirectoryIndex index.php index.html
          </IfModule>
  • MySQL 4.1+ database (MySQL 5.0.19+ recommended for better query optimisation and performance)
    • Note: We have sorted out the bugs with Fez and MySQL 5, and are running our testing and production servers with MySQL 5.0.19.
    • Important: Edit your MySQL my.cnf config file. Under [mysqld] add (or change) ft_min_word_len=2. This makes the full text index include two length words which is necessary for Fez to run.
  • PHP 5+ (Fez uses the new PHP5 DOM Document XML functions to handle XML objects so PHP4.x will not run Fez).
    • PHP 5.1 is also tested to be ok and it is what we use on our test and production servers.
    • These PHP extensions must be enabled and the libraries installed where neccessary (the links take you to the php manual with installation instructions for each extension):
      • Tidy - for linux make sure libtidy, libtidy-dev and tidy packages are installed before compiling php
      • LDAP
      • GD version 2+
      • MySQL
      • CURL
    • WARNING!: When compiling PHP we have noticed that DOMXPATH does not work with some versions of LIBXML2. We have successfully tested using DOMXPATH with LIBXML2 version 2.6.16 (on Linux Centos) and 2.6.23 (latest version of LIBXML on Redhat Fedora 4), but it causes a failure in PHP with version 2.6.19 (on Linux Red Hat Fedora 4). We have only tested these three versions so others may work or fail as well.
    • NOTE: We are still ironing out some minor PHP4 to PHP5 changes so you may notice some 'notices' or 'warnings' with the PHP error level set to anything other that 'E_FATAL'. These notices and warnings can be safely ignored and will dissapear in future Fez releases.
    • PHP.ini configuration requirements:
      • allow_call_time_pass_reference = On (Fez may not need this in future releases, especially since it will probabaly be deprecated in PHP6)
      • date.timezone = your timezone eg Australia/Queensland see http://www.php.net/manual/en/timezones.php
    • PHP.ini configuration recommendations:
      • upload_max_filesize = 10M (default is 2M, but if you want to upload more than 2 megabyte files then change this so suit).
  • Image Magick (for thumbnail, webformat and preview format resizing)
    • For Windows servers you will need to install the dll version available on the Image Magick website
      • Make sure you add the Image Magick directory containing the 'identify' and 'convert' executables in the windows environment path. To do this right click on 'My Computer', click 'properties', click the 'Advanced' tab, click 'Environment Variables', then edit the system variable 'PATH' and add the image magick executable directory to the end. Each directory entry in the PATH string is seperated by a semicolon (;).
    • For Linux you can download the source and compile it, or use one of the binaries for your Linux distro
      • For Linux Fez expects the IM commands 'identify' and 'convert' to be in certain locations set in the Fez config.inc.php. Make sure they are the correct paths and change the config.inc.php settings if necessary. You can find where identify and convert are by doing a 'which convert' command in the linux shell. This will give you the correct full path to put into the Fez config.inc.php file.
  • Graphviz (for workflow diagrams)
    • For Windows servers you will need to install the windows install executable version. The windows installer adds the executable directory to the PATH environment variable automatically.
    • For Linux you can install the RPM package on the Graphviz site or install it from source. Make sure the 'dot' executable path is in the PATH environment variable.
  • JHOVE (for preservation metadata extraction)
    • Be sure to edit the jhove.bat (windows) or jhove command (linux) and set the JHOVE_HOME and other variables inside them as per the JHOVE installation instructions. This can also be done with the configure.pl perl script in the JHOVE distribution.
      • Fez expects JHOVE to be in /usr/local/jhove for linux or c:/jhove for windows. If you install jhove to different directories to this then update the Fez config.inc.php with the correct locations.
      • You will need to change the last line in the jhove executable 'jhove' (so JHOVE can find its configuration file correctly):
        • FROM: ${JAVA} -classpath $CP Jhove $ARGS -c ${JHOVE_HOME}/conf/jhove.conf
        • FOR LINUX TO: ${JAVA} -classpath $CP Jhove -c ${JHOVE_HOME}/conf/jhove.conf $ARGS
        • FOR WINDOWS TO: %JAVA% -classpath %CP% Jhove -c %JHOVE_HOME%/conf/jhove.conf %ARGS%
How do I install Fez?
Please follow these steps:
  1. Download the latest Fez release from SourceForge here
  2. Uncompress to a folder in your htdocs Apache directory
    • Note: You may wish to set the Fez directory up as "Virtual Host" or as the "Document Root" in your Apache httpd.conf file.
    • If you are using Linux then make sure the user that runs the apache service has rights to be able to write files to the fez folders. Apache/PHP will need to write the config.inc.php file, create the templates_c directory, and the error_handler.log file.
  3. Open your web browser and load the "http://yourserver.com/fez/setup/". This will load the config setup interface.
    • Note: If some of the PHP requirements are missing the setup script will ask you to install them first, rather than show the config form. This PHP requirements check cannot check for all the above requirements so even if there are no warnings Fez may not work.
  4. Fill in the setup config details and click "Start Installation".
    • Note: We recommended moving the error_handler.log and the config.inc.php files below the apache document root to be more secure. Or at least setting the security error_handler.log to be write only by the web server user.
What if I encounter problems?
Please see the troubleshooting section in the FAQ. If your problem is not the FAQ you can join and email the fez users email list at http://lists.sourceforge.net/lists/listinfo/fez-users

Getting Started

 
 
How can I quickly get started using Fez?
 
  1. Open your web browser and load "http://yourserver.com/fez/. It should show the Fez front page.
  2. Login with username "admin", password "admin".
  3. Click on the Administration tab, then the Manage Users link.
  4. Change the admin user password to something more secure.
    • You can setup other users in here and set them to be Fez Administrators
    • If LDAP is ticked for a user Fez will authenticate against the LDAP server setup in your config.inc.php
  5. Go to the "browse communities" tab link.
  6. Create a new community
    • Remember to assign yourself as an editor if you want the community to show up in your "My Fez" area. Administrators will see all collections however.
    • In this initial release of Fez security is applied at the community level and inherited by that communities collections and records, it will be made more granular in future releases
  7. Create a new collection under the new community
    • Remember to add document types to the collection.
  8. Create records in the collection.

A more detailed user and admin guide for Fez will be will be available soon.
Company Proprietary
Copyright © 2003-2004 Jason Robbins. All rights reserved. License terms. Retain this copyright statement whenever this file is used as a template.