Table of Contents

Getting Started
Compiling a Source Distribution
Setting up the Server's Relational Database
Configuring the Fedora Server
Running the Server
Configuring Fedora to Run on a Different Host or Port
Server logs
Where From Here?

Getting Started

About This Guide

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.

Install Prerequisite Software

Required:

  • Sun's Java Software Development Kit, v1.4.2. Whether you are installing a binary or source distribution, you must have the J2SDK v1.4.2 or above. It should be installed on the machine you intend to use as the Fedora server. You can download it at http://java.sun.com/

Optional:

  • MySQL, v3.23.x, MySQL 4.x, or Oracle 9i The Fedora server is backed in part by a relational database. If you decide not to use the included pure java database, McKoi v1.0.3 (more about that later), you should download and install one of the known, working databases for your platform (or see the "Other Databases" section below). You can download MySQL at http://www.mysql.com/. (Please note that issues have been reported when using older versions of the Windows implementation of MySQL v3.23.53 - v3.23.58 with Fedora. For running under Windows, we recommend using the current production version of MySQL for Windows. )

Download Fedora

The latest version of the software can always be found at http://www.fedora.info/download/

There are multiple distribution packages in a release. The server binaries, the client binaries, and the entire source code. Each of these packages is distributed in .tar.gz (for Unix) and .zip (for Windows) archives.

Unpack Fedora

Server binary distribution:

  • Decide where you want the Fedora software to reside. For example, C:\ or /usr/local.

  • Unpack the archive in that directory. It will create its own directory, named according to the version... like fedora-2.1. This will be the home directory of Fedora.

  • If you're in Unix, you must change the permissions of the files in the server/bin directory so that you can execute them. For instance, if you installed in /usr/local, this can be done with the command chmod 755 /usr/local/fedora-2.1/server/bin/*

Client binary distribution:

  • If a server is already unpacked on the machine, put the client in the same place. That is, if your server is unpacked into C:\fedora-2.1\server\, go to C:\ and unpack the client from there. It will go into C:\fedora-2.1\client, so that now both the client and server are under one common directory.

  • If the machine you're installing on doesn't have a server, decide where you want the client to reside. For example, C:\ or /usr/local. Then unpack the archive in that directory. It will create its own directory, named according to the version... like fedora-2.1. This will be the home directory of Fedora.

  • If you're in Unix, you must change the permissions of the files in the client/bin directory so that you can execute them. For instance, if you installed in /usr/local, this can be done with the command chmod 755 /usr/local/fedora-2.1/client/bin/*

Source Code:

  • Decide where you want to work with the source code and unpack it there. It will create its own directory, named according to the version... like fedora-2.1-src. This will be your Fedora development directory.

Prepare Environment Variables

For server, client, and source code installations:

  • JAVA_HOME must point to the base directory of your J2SDK installation. On Windows, this will usually be something like C:\j2sdk1.4.x\. On Unix, it could be in several places. The /usr and /usr/local directory are commonly used for Java installations.

    Note for server and client installations: If you would rather not set your JAVA_HOME to point to the version required by Fedora (for instance, if you run other applications using java1.3) you can instead set the FEDORA_JAVA_HOME environment variable. This way, Fedora's java installation won't conflict with your other java applications.

    Note for source installations: JAVA_HOME must be set to the values stated above, since ant requires this environment variable.

  • PATH must contain the executable (bin) directory of the J2SDK installation. This is usally just under JAVA_HOME.

For server and client installations:

  • FEDORA_HOME must point to the base directory of your Fedora installation. You will choose this directory when you unpack a binary distribution.

For server installations:

  • PATH must contain the executable directory of the Fedora server software installation. This will be $FEDORA_HOME/server/bin on Unix, or %FEDORA_HOME%\server\bin in Windows.

For client installations:

  • PATH must contain the executable directory of the Fedora client software installation. This will be $FEDORA_HOME/client/bin on Unix, or %FEDORA_HOME%\client\bin in Windows.

For source code installations:

  • FEDORA_DEV should contain the directory under which the source was unpacked, including the version part of the path. For instance, if you installed the source in C:\ and it unpacked into C:\fedora-src-2.1\, FEDORA_DEV should be C:\fedora-src-2.1

  • PATH should contain the bin directory of Ant. If you don't already have Ant installed, or you have a version before v1.6.2, you can use the version that comes with the Fedora source distribution in under %FEDORA_DEV%\res\apache-ant-1.6.2\bin (in Windows) or $FEDORA_DEV/res/apache-ant-1.6.2/bin (in Unix). IMPORTANT: If you use your own version of Ant, be sure it's v1.6.2+ or the build may not work. You can verify this by typing "ant -version" at the command prompt. Note: If you opt to use the ant binaries included with the source, and you're in Unix, be sure to change the permissions on the files in the bin directory so that you can execute ant. This can be done with the command: chmod 755 $FEDORA_DEV/res/apache-ant-1.6.2/bin/*

Compiling a Source Distribution

It's Easy

Provided that you've followed all the appropriate instructions above, you can now go to the $FEDORA_DEV directory and type:

ant serverdist

and everything necessary for a server and client distribution will be put in $FEDORA_DEV/dist

If you want to run the server and client straight from where it was compiled, be sure to set your FEDORA_HOME to $FEDORA_DEV/dist, and add $FEDORA_HOME/server/bin and $FEDORA_HOME/client/bin to your PATH environment variable.

For other targets, see the build.xml file or type ant -projecthelp for a brief description of each.

To erase all temporary and compiled files created by a build, first ensure that your database and Fedora server are stopped, and type ant clean. If you're not using McKoi, you should also drop the fedora21 (or whatever you named it) database from your RDBMS if you want to start fresh.

Setting up the Server's Relational Database

Initialize the Database

Fedora is designed to be RDBMS-independent, but comes with a pure java database called McKoi. It has been tested and works with McKoi, MySQL and Oracle 9i. If you choose to use any database but McKoi, we assume here that it is already installed.

Follow the below instructions for the RDBMS of your choice in order to create the user and tablespace so that the Fedora software can use the database.

McKoi

Execute the command:

mckoi-init fedoraDBUser fedoraDBPass

...where the first parameter is the username you'd like to use for the database, and the second parameter is the password you'd like to use. Remember this information, as it will be needed later when configuring Fedora.

Username and password values are case sensitive.

Note: This command resolves to a batch file (mckoi-init.bat) in Windows, and a shell script (mckoi-init.sh) in Unix. These reside in the server's bin directory.

MySQL

Execute the command:

mysql-config installDir dbaUser dbaPass fedoraDBUser fedoraDBPass dbName mysql41_flag

Where:

  • installDir is the location where MySQL is installed. In Unix, this might be /usr/local/mysql. In Windows, it might be C:\mysql.   In Windows, use double quotes if the path
    contains spaces    , e.g. "C:\Program Files\MySQL\MySQL server 4.1")

  • dbaUser is the name of the MySQL user with dba privileges. In a default MySQL installation, this will be root.

    Please note that dbaUser is case sensitive.

  • dbaPass is the password of the MySQL user with dba privileges. In a default MySQL installation, if you're running MySQL on the same machine as Fedora, you can usually pass "" for this argument.

    Please note that dbaPass is case sensitive.

  • fedoraDBUser is the username you'd like to use for the Fedora software's database access. (e.g., fedoraAdmin) Please note that this value is case sensitive.

  • fedoraDBPass is the password you'd like to use for the above user. (e.g., fedoraAdmin) Please note that the password is case sensitive.

  • dbName is the name you'd like to use for the Fedora database. (e.g., fedora21) Please note that the user name is case sensitive.

  • mysql41_flag is an optional paramter that is only used if you are running MySQL 4.1.x. If using MySQL 4.1.x Fedora requires that you set the default character set to "utf8" and the default collation to "utf8_bin" for the Fedora database. Any value may be used for this parameter. If present, the script will automatically set the default character set to "utf8" and the default collation to "utf8_bin" for the Fedora SQL database. If you are running versions of MySQL prior to 4.1, OMIT THIS PARAMETER.

Note: This command resolves to a batch file (mysql-config.bat) in Windows, and a shell script (mysql-config.sh) in Unix. These reside in the server's bin directory.

Important: Fedora comes installed with version 3.1.10 of the MySQL Connector/J JDBC driver that is compatible with MySQL v3.23.x, 4.0.x, and 4.1.x. If you plan to use MySQL 4.1.x, be sure to follow the note above referring to the mysql41_flag option on the mysql-config database configuration script.

Important: If you are installing Fedora under Windows and plan to use an earlier version of MYSQL (e.g., 3.23.53 thru 3.23.58), you should use all lower case characters when specifiying the Fedora database name when running the mysql-config.bat script (e.g., "myfedoradb" instead of "MyFedoraDb").

Oracle 9i

With Oracle 9i, you will need to use an administrative account to manually create 1) the fedora user on the db, and 2) the tablespace on which that user has complete control.

Then you'll need to make sure the Fedora server has the JDBC driver necessary to connect to the database. You can download the appropriate Oracle JDBC driver from http://technet.oracle.com/software/tech/java/sqlj_jdbc/content.html. This will come with a file called ojdbc14.jar. You will need to put that file on your Fedora server, in the directory: FEDORA_HOME/server/jakarta-tomcat-5.0.28/common/lib.

Then you should modify the Fedora Server Configuration File (FEDORA_HOME/server/config/fedora.fcfg) and ensure that the datastore entry (near the bottom) for Oracle points to the right host and database. The fedora.fcfg file that comes with the distribution uses a database on the local host named "fedora21".

When you start fedora, be sure to use the parameter "oracle", as in fedora-start oracle. Starting the server is more fully explained later.

Other Databases

If you want to use a different database, it's an option, but it will take some extra work. Here's how it can be done:

  • The database needs to be JDBC-compliant and must support common SQL-92 syntax. The driver will need to be put in the server's jakarta-tomcat-5.0.28/common/lib directory so that Fedora picks it up, and 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 they don't exist, it creates them. Creation of tables is a much less standardized task across RDBMSs than regular SQL queries. Thus, you must either

  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 your own subclass of fedora.utilities.DDLConverter for your database software, include it in a jar file in server/jakarta-tomcat-5.0.28/common/lib, and associate it with the JDBC driver inside the 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.

 

Configuring the Fedora Server

 1. STEP ONE:  Run the Fedora Setup Utility to establish your base security settings!

Beginning with Fedora 2.1, the method of configuring the server has changed. Before starting for the first time, you must run the Fedora Setup Utility (fedora-setup) to select a base security configuration and initialize the server with your base configuration using the fedora-setup command-line utility. This process is described in detail in the Securing Your Repository document. Once fedora-setup has been run you can then customize the generated configuration files as needed.

2. STEP TWO:  Edit the Fedora Server Configuration File (fedora.fcfg) to override default settings.

The Fedora server configuration file contains: (1) global parameters for the Fedora server, (2) configuration parameters for each server module, and configuration parameters for each persistent data store of the Fedora server.   The configuration file is located at FEDORA_HOME/server/config/fedora.fcfg.

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. Examples include the level of logging to do, the port on which the server should be exposed, and the superuser password.

The module elements are used to configure specific parts of Fedora. For instance, the module with the role attribute, "fedora.server.search.FieldSearch" 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. Important ones will be listed below.

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 fedora.server.storage.ConnectionPoolManager module refers to one of the datastore elements in it's value.

Important Configuration Parameters

You will probably want to change the values of the following parameters for you own installation. Items in bold must be changed prior to running the server for the first time. Other items may require changes depending on your environment. For instance, object_store_base should be changed if you're running the server in Unix, as the default value is windows-specific. All configurable items are described in detail in the fedora.fcfg file. Parameters that are new or that have changed since Fedora 2.0 are highligted in red.

adminUsername

This is where you set the value of the administrative username. This is used when authenticating remote requests for performing administrative functions. The default value for username is fedoraAdmin. Note that this username must also be known by your authentication application of choice. By default, this is the tomcat-users_fedoraTemplate.xml file which includes the username fedoraAdmin with a role of fedoraRole="administrator". If you change the username in fedora.fcfg, you must also updated the entry in tomcat-users_fedoraTemplate.xml or you other authentication application of choice. See Securing Your Repository for additional information.

adminPassword

This is where you set the value of the administrative user, "fedoraAdmin"'s password. This is used when authenticating remote requests for performing administrative functions. Please note that this password is case sensitive. As noted for username, any changes to this value must also be reflected in your authentication database.

log_level

Indicates the amount of detail to include in the server logs. The default level is warning, which only writes log messages when problems occur. To get as much detail as possible for debugging purposes, set this value to finest.

object_store_base
A directory where digital object XML wrappers (FOXML files) will be stored. This directory will be created if it doesn't already exist. The default value for this parameter is a the following relative directory path:  fedora21/store/datastreams.   You can change this to another relative directory path or an absolute directory path.
 
datastreams_store_base
A directory where datastreams of digital objects will be stored. This directory will be created if it doesn't already exist. The default value for this parameter is a the following relative directory path:  fedora21/store/datastreams.   You can change this to another relative directory path or an absolute directory path.
 
fedoraServerPort

The port on which the server should run. 8080 is often used, but this can be anything your OS / user privleges will allow.

fedoraShutdownPort

The port on which the server is shutdown. Port conflicts can arise if you are running multiple instances of a tomcat or Fedora server on the same machine. Fedora uses the default shutdown port number of 8005. If you are running other standalone instances of tomcat or Fedora on the same machine, each instance will require a unique shutdown port. This parameter allows you to change the port number used to shutdown the Fedora server to avoid potential port conflicts with other servers.

fedoraRedirectPort

The port on which the server is redirected. Port conflicts can arise if you are running multiple instances of a tomcat or Fedora server on the same machine. Fedora uses the default redirect port number of 8443. If you are running other standalone instances of tomcat or Fedora on the same machine, each instance will require a unique redirect port. This parameter allows you to change the port number used to redirect the Fedora server to avoid potential port conflicts with other servers.

fedoraServerHost
The fully qualified host name of the machine on which Fedora runs. If the machine has aliases, use the alias that will be used by people connecting to the server (be it via a web browser or one of the SOAP API exposures).

NOTE:  Ingesting Fedora demo objects:  If you have changed the values of either fedoraServerHost and fedoraServerPort, then you must run the demo object converter utility script to change the host and/or port in the demo object ingest files.   The demo objects are shipped with references to "localhost:8080" and these references must reflect the new values of fedoraServerHost and fedoraServerPort .  Refer to the Command-line Utilities documentation for additional details on running the demo object converter.

 
WARNING: If you are using Fedora's XACML-based policy enforcement - Before you change the server IP address or hostname to something other than 127.0.0.1 (or "localhost"), you should initially start the server with the default hostname value (i.e., 127.0.0.1 or "localhost").   This initial starting of the server will make sure that Fedora's default XACML policies are properly configured and placed in the proper directories.   Once the default policies are in place, you can shutdown the server and change the hostname at any time.   Also see the instructions below on how to change the server IP address or hostname for a checklist of places that you may need to make configuration changes.   

WARNING:  If you plan to create custom disseminators on your digital objects AND if your server is setup to authenticate API-A requests -  Make sure that the server hostname is an externally resolvable IP address (NOT "localhost").   Remember,  API-A authentication is enabled if  you ran the Fedora Setup Utility with either "ssl-authenticate-all" or "no-ssl-authenticate-all"  ("-all" means authenticate both API-A and API-M).  Since a disseminator uses an external service that must call back to the repository, the server must have a fixed IP address for the repository, resolvable via DNS.   Once there is a fixed repository location for the external service to call back to, then you can set up authentication settings for the external services as described in Backend Services Security Configuration.  NOTE:  You do not need to worry about this if your server is NOT authenticating API-A  (if you selected either "ssl-authenticate-apim" or "no-ssl-authenticate-apim" when you ran the Fedora Setup Utility).    

 
Authorization/REPOSITORY-POLICIES-DIRECTORY
A directory where XACML repository-wide policies will be stored. This will be created if it doesn't already exist. This parameter must be given as an absolute path. The default value for this parameter is /fedora-xacml-policies/repository-policies. For information on the policy enforcement module configuration, see Fedora Authorization with XACML.    For information on writing policies see Fedora XACML Policy Writing Guide.
Authorization/SURROGATE-POLICIES-DIRECTORY
A directory where XACML surrogate policies will be stored. This will be created if it doesn't already exist. This parameter must be given as an absolute path. The default value for this parameter is /fedora-xacml-policies/surrogate-policies.  For information on the policy enforcement module configuration, see Fedora Authorization with XACML.    For information on writing policies see Fedora XACML Policy Writing Guide.
Authorization/REPOSITORY-POLICY-GUITOOL-POLICIES-DIRECTORY
A directory where XACML policies generated by the future Policy Tool GUI will be stored. This will be created if it doesn't already exist. This parameter must be given as an absolute path. The default value for this parameter is /fedora-xacml-policies/repository-policies-generated-by-policyguitool. This parameter is not currently active in the code and is for future use.
DOManager/pidNamespace

This is the namespace id part of newly generated PIDs for objects. This should be a short string consisting of the characters [a-z][0-9] and the hyphen ("-") character. When objects are first ingested or created in the repository, this will be the first part of the identifier used for them. (Note: the pid namespace won't be used for objects that are ingested with a "demo:" pid)

DOManager/retainPIDs

This parameter defines the namespaces of PIDs to retain during the ingest process. When an object is ingested, Fedora normally allocates a unique PID within pidNamespace for it regardless of what PID actually exists in the object. This option provides a way to override that behavior on a per-pid-namespace basis. If specified, this should be a space-delimited list of pid namespaces that will be accepted in the object as-is. By default, this list includes the namespaces of "test" and "demo".

DOManager/storagePool

This specifies the database connection pool to be used for the storage subsystem. Normally this will just identify ConnectionPoolManager's default connection pool.

Management/allowHosts

This parameter has been removed from fedora.fcfg. IP restrictions are now handled using XACML policies. For additional information regarding policy writing see Fedora XACML Policy Writing Guide.

Management/denyHosts

This parameter has been removed from fedora.fcfg. IP restrictions are now handled using XACML policies. For additional information regarding policy writing see Fedora XACML Policy Writing Guide.

Access/allowHosts

This parameter has been removed from fedora.fcfg. IP restrictions are now handled using XACML policies. For additional information regarding policy writing see Fedora XACML Policy Writing Guide.

Access/denyHosts

This parameter has been removed from fedora.fcfg. IP restrictions are now handled using XACML policies. For additional information regarding policy writing see Fedora XACML Policy Writing Guide.

Access/doMediateDatastreams

This parameter controls the pseudo-proxy service used between the Fedora server and backend services. If basic authentication for API-A is disabled, there is no need for this service and it should be set to false. If basic authentication for API-A is enabled, it should be set to true. The value for doMediateDatastreams is preset to the correct value in each of the four base security configurations so you should not need to change it if using one of the four base security configuration. Refer to Securing Your Repository for more information about the base security configurations.

FieldSearch/connectionPool

Specifies the database connection pool to be used for the fielded search functionality. Normally this will be ConnectionPoolManager's default pool.

OAIProvider/repositoryName

How you want your repository to be named in the OAI-PMH interface's Identify request.

OAIProvider/repositoryDomainName

This will be used in conjunction with the pidNamespace to uniquely identify the items in your repository to OAI harvesters. The default value is example.org, but you'll want to change it to the domain name where the repository is hosted.

OAIProvider/adminEmails

Who the OAI-PMH interface identifies as administrators to harvesters. This is a space-separated list.

OAIProvider/friends

A space separated list of OAI-PMH provider endpoints identifying other providers that you associate with. OAI harvesters use this for discovery purposes.

ConnectionPoolManager/defaultPoolName

The pool to be provided to modules that request the default connection pool.

ConnectionPoolManager/poolNames

A comma delimited list of pools to make available. These should be identified by the id attribute of one of the datastore elements.

datastore/jdbcDriverClass

Identifies the driver to use for connecting to the database. This is RDBMS-specific. If you need to use a driver that isn't already included, put the .jar file in server/jakarta-tomcat-5.0.28/common/lib./

datastore/jdbcURL

A JDBC URL that can be used to connect to your database. The syntax must match that required by the driver. Working examples for MySQL and McKoi are included.

datastore/dbUsername

The username for database access. This should match the username used previously when setting up the database for Fedora.

datastore/dbPassword

The password for the database user. Please note that this value is case sensitive.

datastore/maxActive

The maximum number of active instances in a connection pool.

datastore/maxIdle

The maximum number of active instances in a connection pool.

datastore/minIdle

The minimum number of idle instances in a connection pool.

 
resourceIndex/level
A required parameter indicating the indexing level for the Resource Index. For more information see the Resource Index Guide.  The valid indexing settings are:
 
0 = OFF  - this disables the Resource Index
1 = ON   - for each digital object, this will index key object properties, Dublin Core (DC datastream), RDF relationships/properties (RELS-EXT datastream), and any non-parameterized dissemination methods
2 = ON  - for each digital object, this will index everything at the level 1, plus any parameterized dissemination methods that have have a domain of fixed parameter values
 
WARNING: changing the level to either 1 or 2 requires a rebuild of the Resource Index.  Consult the documentation for the Fedora Rebuild Utility. 
 
resourceIndex/datastore

A required parameter indicating the ame of the triplestore to use. WARNING: changing the triplestore requires a full dump-and-load of the repository. The default value is datastore="localKowariTriplestore". For more information see the Resource Index Guide.

resourceIndex/aliases

An optional parameter indicating aliases that can be used for queries. The param name of an alias starts with the string "alias:" and is followed by the name of the alias (shortcut) for the value, which is a URI prefix. F or example: name="alias:test" value="http://example.org/terms#" will allow a query to use test:apple instead of http://example.org/terms#apple The default value is datastore="http://example.org/terms#". For more information see the Resource Index Guide.

Other Server Configuration Parameters

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

 

Running the Server

Start The Database

If the database isn't already started, start it now.

If you've chosen to use the included mckoi database, you can simply type "mckoi-start" and the database will start

Start The Server!

Fedora is normally started with the command:

fedora-start

The configuration file, fedora.fcfg, can be written so that it takes a parameter which has the effect of using an alternate value for some of the <param...> elements, if an alternate parameter exists. The default fedora.fcfg assumes that you're using MySQL, but has been written to use the mckoi database if you start it with:

fedora-start mckoi

...so if you're using mckoi, start it with the above command instead.

Read the fedora.fcfg file and look for the attributes named "mckoivalue" to see how this is done, if you're curious or would like to define your own parameter. You can also change the fedora.fcfg so that it doesn't have to take the "mckoi" parameter in order to run with mckoi (simply set the value of the parameters to that of the mckoivalue attributes so that these values are taken by default.

Note for Unix users: The commands fedora-start and fedora-start mckoi do not have to be run by root.

Stopping the Server

You can stop the Fedora server with the command:

fedora-stop

The database should be shut down only after the Fedora server has been stopped. If you're using mckoi, you can stop it with the command:

mckoi-stop [dbUser] [dbPassword]

Other databases will have their own shutdown scripts or commands.

 

Configuring Fedora to Run on a Different Host or Port

The Fedora server now has internal support for avoiding breakage of self-referential URLs (i.e., URLs that contain the hostname and port of the Fedora server itself). This change allows the Fedora server host and port to be re-configured without breaking digital objects that contained URLs that referred to a previous host and port configuration.

The host name and port number on which the Fedora server runs is controlled by the fedoraServerHost and fedoraServerPort parameters in the fedora.fcfg configuration file. By default, these are set to the host name of localhost and port number of 8080. The steps you need to take in order to change host name and/or port number vary slightly depending on whether you are making the change for the first time or making the change on a pre-existing Fedora server.

If you are installing Fedora for the first time, or if you are changing the host or port on an existing Fedora installation, you need to make the following configuration changes:

  1. Stop the Fedora server if it is already running.
     
  2. Required: Change the values of fedoraServerHost and fedoraServerPort  in the Fedora server configuration file ($FEDORA_HOME/dist/server/config/fedora.fcfg).
     
  3. Optional (only if XACML Policy enforcement is enabled):  If Fedora's Authorization module is enabled (i.e., ENFORCE_MODE="enforce-policies") AND  you have created custom disseminators on digital objects, you must enter the fixed IP address of your server in two places:

    a.  Fedora's Backend Services Security Configuration:   Since custom disseminators typically use an external services to transform digital object content,  these "backend" services must be configured to communicate securely with the Fedora repository server.   Please consult the instructions found in Backend Services Security Configuration.    This document will tell you how to use Fedora's  web interface for backend service configuration.  From the web form, you will enter the IP address of the server host for all of the following backend service entries:  (1) "fedoraInternalCall-1"  (2) "fedoraInternalCall-2"  and (3) the services installed alongside the Fedora repository (on the same machine) to support the Fedora demo objects.  Note that all of these service entries are pre-configured with the loopback IP address of 127.0.0.1 and your job is to simply add the fixed IP address of your server for each backend service entry that already contains the loopback IP address.  

    b.  Default XACML Policies:   It is also essential that you add your server's fixed IP address to the default XACML policies that ship with Fedora.  Defaul policies are found in the /default subdirectory of the repository-policies you configured in the Authorization module for the server.    The specific policies that must contain your server's fixed IP address are: (1) deny-apim-if-not-localhost.xml, (2) deny-reloadPolicies-if-not-localhost.xml, and (3) deny-serverShutdown-if-not-localhost.xml).  If you edit the policy xml file, you will see the loopback IP address of 127.0.0.1 in the policy condition.  Simply add another entry below this with your fixed IP address.   For more information on these policies, see  Fedora Authorization with XACML.
     
  4. Start the Fedora server.

NOTE:  Fedora Admin Client Usage:  When invoking the Fedora admin-client, remember to specify the new host name and/or port number when invoking the client. e.g., fedora-admin hostname port fedora-username fedora-password.  Please note that all user names and passwords are case sensitive

NOTE:  Ingesting Fedora demo objects:  If you have changed the values of either fedoraServerHost and fedoraServerPort, then 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, they will be fine!  The demo objects are shipped with references to "localhost:8080" and these references must reflect the new values of fedoraServerHost and fedoraServerPort .  Refer to the Command-line Utilities documentation for additional details on running the demo object converter.

 

Server logs

While the server is running, it writes logs to FEDORA_HOME/server/logs. These are timestamped files, written in a simple XML format. You can use these logs to get more extensive information about what the server is doing or to diagnose problems.

 

Where From Here?

If you've just got your Fedora server up and running, 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.

The demos may be ingested via the Fedora Admin GUI tool or from the command line. If you ingest the from the Admin GUI, you must be sure to ingest bdef objects first, then bmech objects, then regular objects.

To access the Admin GUI use the command:

fedora-admin [hostname] [port] [username] [password]

To ingest the demos from the command line (recommended), use the command:

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.