Table of Contents

  1. Introduction
    1. Install Prerequisites
    2. Download Fedora
    3. Prepare Environment Variables
  2. Installation
    1. Quick Install
    2. Custom Install
    3. Client Install
  3. Running the Fedora Server
    1. Demo Objects
  4. Database
    1. MySQL
    2. Oracle
    3. PostgreSQL
    4. Other
  5. Configuring the Fedora Server
    1. fedora.fcfg
    2. Logging
  6. Installation from Source
  1. Introduction

    This is the installation guide for Fedora. It includes instructions for installing the server and client distributions, as well as instructions for installing and compiling the complete source code distribution.
    1. Install Prerequisites

      Java SE Development Kit (JDK) 5.0.
      Whether installing a binary or source distribution, JDK 5.0 is required. The JDK should be installed on the machine you intend to use as the Fedora server. The JDK is available from

      The Fedora server is backed in part by a relational database. To simplify installation, the Fedora installer includes and can configure an embedded instance of the McKoi SQL Database 1.0.3. Fedora also supports MySQL, Oracle 9 and PostgreSQL. If the included McKoi database will not be used, another database server must be installed, configured and running before proceeding with the installation. To configure Fedora to use another database, please see the Database section below for further instructions.

      Servlet Container
      The Fedora installer includes Tomcat 5.5.23. Optionally, Fedora may be installed into any existing servlet container that implements Servlet 2.4/JSP 2.0 or higher. At this time, Fedora has chiefly been tested with Tomcat 5.x but users have reported running Fedora successfully with Jetty and JBoss.

      Additional requirements for building Fedora from source:
      Ant 1.6.5 or later
      Fedora uses Ant for its build environment. Ant is available from
    2. Download Fedora

      The latest version of the software can always be found at

      There are two download options: the Fedora Installer and the source code distribution. Unless you wish to build Fedora from source, you should select the Fedora Installer.
    3. Prepare Environment Variables

      The following environment variables must be correctly defined:

      This should point to the base directory of your Java installation. On Windows systems, this might be C:\java. For UNIX derivatives, this might be something like /usr/local/java-1.5.0-sun

      This is the directory where Fedora will be installed, for example, C:\fedora or /usr/local/fedora. PATH
      This must include the Java and Fedora bin directories. For UNIX derivatives, this will be $FEDORA_HOME/server/bin, $FEDORA_HOME/client/bin and usually $JAVA_HOME/bin. For Windows, this will be %FEDORA_HOME%\server\bin, %FEDORA_HOME%\client\bin and usually %JAVA_HOME%\bin.

      If you will be building from source, Ant should also also be on your path.

      If Fedora is configured to use SSL, JAVA_OPTS must include the and properties. See the SSL section below for more information.

      If Fedora is configured to use Tomcat, CATALINA_HOME must be set before starting Fedora. If using the quick install option, CATALINA_HOME should be set to $FEDORA_HOME/tomcat (or %FEDORA_HOME%\tomcat in Windows).
  2. Installation

    The Fedora Installer provides three installation options: quick, custom, and client.

    To start the installer, change to the directory where you downloaded the installer and at a command prompt, enter:
    java -jar fedora-3.0b1-installer.jar

    Please ensure that the user account that is running the installer has sufficient permissions to write to the directories where Fedora will be installed (if deploying to an existing Tomcat installation, this includes permissions to the Tomcat directory). Installer created files will usually be owned by the user running the installer. Consequently, for example, after installation users of the Fedora Admin client will need write permissions to the the installer created FEDORA_HOME/client log directories.
    1. Quick Install

      The quick option is designed to get Fedora up and running as quickly as possible, with a minimum of advanced options. The quick install will automatically install a servlet container and database. Neither SSL support nor XACML policy enforcement is enabled by the quick install.
    2. Custom Install

      The custom option provides the most flexibility in configuring an installation. Options include the choice of servlet container, database, the host and ports Fedora will be running on, enabling optional services, as well as security options including SSL and XACML policy enforcement.

      Servlet Container
      The installer will automatically configure and deploy to Tomcat 5.0.x and 5.5.x servlet containers. However, if an existing Tomcat installation (as opposed to the Tomcat bundled with the installer) was selected, the installer will not overwrite your existing server.xml, but rather, place a modified copy at FEDORA_HOME/install so that you may review it before before installing it yourself.

      Other servlet containers will require manual deployment of the .war files located at FEDORA_HOME/install.

      Configuring SSL support for Fedora's API-M interface is strongly recommended for production environments.

      If the Tomcat servlet container is selected, the installer will configure server.xml for you. However, as noted above, if an existing Tomcat installation was selected, the installer will not overwrite your existing server.xml.

      Please consult your servlet container's documentation for certificate generation and installation. (In particular, the example certificate provided by the installer for Tomcat should not be used in a production environment).

      If Fedora is configured to use SSL, the JAVA_OPTS environment variable must include the and properties. The value of should be the location of the truststore file and the value of is the password for the keystore. The following values may be used with the sample keystore included with the installer:$FEDORA_HOME/server/

      Resource Index
      If the Resource Index is enabled, Fedora will use Mulgara as its underlying triplestore, with full-text indexing disabled.

      REST API
      The REST API is a new, experimental feature which exposes a subset of the Fedora Access and Management APIs with a REST interface.

      If Messaging is enabled, Fedora will create and send a message via JMS whenever an API-M method is called.
    3. Client Install

      Both the quick and custom options will install the Fedora client software in addition to the Fedora server. The client option, however, will install only the Fedora client software.
  3. Running the Fedora Server

    If you selected the quick install option, you will find Tomcat installed in FEDORA_HOME/tomcat. To run Fedora, start Tomcat by entering:

    (or for Windows)

    If you selected the custom install option, ensure that your database server is running (unless you selected the embedded McKoi option) and start your servlet container if necessary.
    1. Demo Objects

      If you just started Fedora for the first time, it's a good idea to check out the demonstration objects to get an idea of how Fedora works. See the Demo Manual for complete descriptions of the demos.

      NOTE: If, during a custom install, you entered values other than the defaults for fedoraServerHost (localhost) or fedoraServerPort (8080), you must run the demo object converter utility script to change the host and/or port in the demo object ingest files. The demo object conversion is only required if you are ingesting demo objects. If the demo objects are already ingested into the repository (e.g. from a previous installation), there is no need for conversion. The demo objects are shipped with references to "localhost:8080" and these references must reflect the new values of fedoraServerHost fedoraServerPort. Refer to the Command-line Utilities documentation for additional details on running the demo object converter.
      To ingest the demos, at a command prompt, enter:
      fedora-ingest-demos [hostname] [port] [username] [password] [protocol]

      For additional information on the fedora-ingest-demos command, see the documentation for the client command-line utilities. Please note that the demo objects must be ingested before they can be discovered using the default search interface.
  4. Database

    Fedora is designed to be RDBMS-independent. Fedora has been tested with McKoi, MySQL, Oracle and PostgreSQL. The embedded version of McKoi included with the installer is provided as a convenience. Large repositories or repositories concerned with scalability and performance should consider using an alternative database. If you choose to use any database other than the embedded McKoi provided by the Fedora Installer, we assume here that the database is already installed.

    Follow the instructions below for the RDBMS of your choice in order to create the user and tables required by Fedora.
    1. MySQL

      Please note that the MySQL JDBC driver provided by the installer requires MySQL v3.23.x or higher.

      The MySQL commands listed below can be run within the mysql program, which may be invoked as follows:
      mysql -u root -p

      Create the database. For example, to create a database named fedora30, enter:
      CREATE DATABASE fedora30;

      Set username, password and permissions for the database. For example, to set the permissions for user fedoraAdmin with password fedoraAdmin on database fedora30, enter:
      GRANT ALL ON fedora30.* TO fedoraAdmin@localhost IDENTIFIED BY 'fedoraAdmin';
      GRANT ALL ON fedora30.* to fedoraAdmin@'%' IDENTIFIED BY 'fedoraAdmin';

      MySQL 4.1.x users must also specify the default character set for the Fedora database as "utf8" and the default collation as "utf8_bin". For example, to set the default character set and collation on a database named "fedora30", enter:
      ALTER DATABASE fedora30 DEFAULT COLLATE utf8_bin;
    2. Oracle

      To prepare Oracle for use with Fedora, the following steps should be taken by an administrative user.

      First, using the Database Configuration Assistant, ensure that the database you'll be using is created with the UTF8 charset.

      Next, you'll need to create a Fedora tablespace and user in the database. Assuming the administrative user is sys and the SID is fedora30, log in using SQL*Plus using the following command:
      sqlplus sys/PASSWORD@fedora30 as sysdba

      To create a tablespace named fedora_tblspace with data in /var/lib/oracle, enter the following:
      CREATE TABLESPACE fedora_tblspace
      DATAFILE '/var/lib/oracle/fedora_tblspace.dat' SIZE 1024M REUSE

      To create a user fedoraAdmin with password fedoraAdmin, using the fedora_tblspace, enter the following:
      CREATE USER fedoraAdmin IDENTIFIED BY fedoraAdmin
      DEFAULT TABLESPACE fedora_tblspace;

      Using the GRANT command, make sure the user has permission to connect, create, alter, and drop tables sequences, triggers, and indexes in this tablespaces. For example,
      GRANT ALL PRIVILEGES TO fedoraAdmin;

      NOTE: Due to distribution license restrictions, the Fedora Installer does not include the Oracle JDBC driver. Oracle JDBC drivers are available from The installer will prompt you for the location of the driver on your filesystem.
    3. PostgreSQL

      Please consult the documentation at for more detailed information about configuring PostgreSQL.

      Launch the PostgreSQL interactive terminal, psql, (optionally appending the -U argument to connect as a different user).
      psql -d postgres

      To create a user fedoraAdmin with password fedoraAdmin and database named fedora30, enter the following:
      CREATE ROLE "fedoraAdmin" LOGIN PASSWORD 'fedoraAdmin';
      CREATE DATABASE "fedora30" WITH ENCODING='UTF8' OWNER="fedoraAdmin";
    4. Other Databases

      To use a database other than McKoi, MySQL, Oracle or PostgreSQL, the database must support common SQL-92 syntax and you must have a JDBC version 3 driver available.

      The JDBC driver will need to be installed manually. For most containers, the driver may be placed in the Fedora webapp's WEB-INF/lib directory. For Tomcat 5.0.x, however, the driver should be installed to TOMCAT_HOME/common/lib. The JDBC url will need to be configured appropriately in the Fedora Server Configuration File.

      Upon startup, Fedora checks the database for all required tables. If the tables do not exist, Fedora will them. Because table creation is much less standardized task across RDBMSs than SQL queries you must do one of the following:
      1. Create the tables and indexes and auto-increments yourself in your own database (see the file: src/dbspec/server/fedora/server/storage/resources/DefaultDOManager.dbspec in the source distribution for the RDBMS-neutral table specifications).

      2. Write a subclass of fedora.utilities.DDLConverter for your database software, include it in the Fedora WEB-INF/classes directory or in a jar file in the Fedora WEB-INF/lib directory, and associate it with the JDBC driver inside the FEDORA_HOME/server/config/fedora.fcfg file (see how it's done by looking at the MySQLDDLConverter and McKoiDDLConverter associations with their respective drivers in the fedora.fcfg file, and the classes' implementations in the source distribution).
      If you choose option #2, please tell us about it, as it will be useful for other users of Fedora! Option 2 is harder, but it will make future installations of new versions of Fedora (where the db schema will likely change) much easier for you if you plan on using that database later.
  5. Configuring the Fedora Server

    1. fedora.fcfg

      The Fedora Server's configuration is chiefly governed by the Fedora Server Configuration File (fedora.fcfg) located at FEDORA_HOME/server/config/fedora.fcfg.

      The Fedora server configuration file contains:
      (1) global parameters for the Fedora server, (2) configuration parameters for each server module, and (3) configuration parameters for each persistent data store.

      The configuration file has a simple schema. It starts with a server element, under which a series of parameter elements occur, followed by a series of module elements, followed by a series of datastore elements. The parameter elements directly following the root server element are used to control what are considered generic server functionality; for example: the port on which the server is exposed.

      The module elements are used to configure specific parts of Fedora. For instance, the module with the role attribute, "" is used to configure the field-searching component of the server. Inside the module element, several param elements are included. These are specific to that module's implementation. Descriptions of each parameter can currently be found in the configuration file itself.

      The datastore elements are used to configure various databases that might be used by the system. Although the sample configuration file holds several, you will typically only need one. The datastore elements are associated with the modules by means of a parameter inside the associated module. In the sample configuration file, for example, the poolNames param of the module refers to one of the datastore elements in its value.

      There are many other parameters you can configure with Fedora. Refer to the Fedora Server Configuration File itself (fedora.fcfg) for internal documentation on all the parameters.
    2. Logging

      Fedora uses Log4J for logging. For detailed information about using Log4J, consult the Log4J Manual:

      The log configuration file is located at FEDORA_HOME/server/config/ Changes to the logging configuration will not be reflected until Fedora is restarted.

      Normally, coarse-grained logs for Fedora are written to FEDORA_HOME/server/logs/fedora.log. The following examples show the kinds of configuration changes you can make to aid in debugging.

      To change the level to DEBUG for all Fedora classes, change the log4j.logger.fedora line to the following:
      log4j.logger.fedora = DEBUG, FEDORA

      To change the level to DEBUG for just one class, add the following lines:
      log4j.logger.fedora.server.utilities.SQLUtility = DEBUG, FEDORA
      log4j.additivity.fedora.server.utilities.SQLUtility = false

      To change the level to DEBUG for a whole package, add the following lines:
      log4j.logger.fedora.server.resourceIndex = DEBUG, FEDORA
      log4j.additivity.fedora.server.resourceIndex = false

      To send all DEBUG messages for a package to STDERR, with methods and line numbers add the following lines: = DEBUG, SECURITY = false
      log4j.appender.SECURITY = org.apache.log4j.ConsoleAppender = System.err
      log4j.appender.SECURITY.layout = org.apache.log4j.PatternLayout
      log4j.appender.SECURITY.layout.ConversionPattern = %p %d{HH:mm:ss.SSS} [%t] (%c{1}.%M:%L) %m%n

      To send all DEBUG messages for a package to a dedicated file, with methods and line numbers, add the following lines: = DEBUG, SECURITY = false
      log4j.appender.SECURITY = org.apache.log4j.RollingFileAppender
      log4j.appender.SECURITY.File =
      log4j.appender.SECURITY.MaxFileSize = 20MB
      log4j.appender.SECURITY.MaxBackupIndex = 5
      log4j.appender.SECURITY.layout = org.apache.log4j.PatternLayout
      log4j.appender.SECURITY.layout.ConversionPattern = %p %d{HH:mm:ss.SSS} [%t] (%c{1}.%M:%L) %m%n

      Note: if log4j.appender.SECURITY.File is left empty, the file will be automatically created at FEDORA_HOME/server/logs/security.log
  6. Installation from Source

    After unpacking the source distribution, change into the newly extracted directory. To build the installer, at a command prompt, enter:
    ant installer

    Once the installer target has been run, you will be able to run the Fedora installer application. To start the installer, change to the FEDORA_HOME/dist directory and at a command prompt, enter:
    java -jar fedora-3.0b1-installer.jar

    Please ensure that the user account that is running the installer has sufficient permissions to write to the directories where Fedora will be installed (if deploying to an existing Tomcat installation, this includes permissions to the Tomcat directory). For more information of the Installer, see the Installer instructions in Section 2 of this document.

    To see a list of other build targets in the source distribution, at a command prompt, enter:
    ant -projecthelp