Disclaimer
==========
This guide is geared towards helping novice users setup Fedora Commons repository. 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".

Conventions
===========

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

1. Introduction
Fedora (or Flexible Extensible Digital Object Repository Architecture) (not to be confused with the Linux distribution named Fedora) is a modular architecture built on the principle that interoperability and extensibility is best achieved by the integration of data, interfaces, and mechanisms (i.e., executable programs) as clearly defined modules. Fedora is a digital asset management (DAM) architecture, upon which many types of digital library, institutional repositories, digital archives, and digital libraries systems might be built. Fedora is the underlying architecture for a digital repository, and is not a complete management, indexing, discovery, and delivery application. (Source Wikipedia)

2. Installation Prerequisites

2.1 Sun Java Development Kit
a) Go to http://java.sun.com/javase/downloads/index.jsp and download the JDK (the current, at the time of writing, is JDK 1.6 update 17). Choose the *-rpm.bin version to download.
b) After downloading, as a root user execute:

c) It will display the End User License Agreement (EULA), which you have to scroll down (press [SPACE] key to scroll). At the end, it will ask you if you accept or deny the license, type "yes" at the prompt and press [Enter]. It will take a while it generates files and installs the JDK on your machine. After a few minutes, the installation shall open a browser window, close that window, and the installation will be complete.
d) Next, you need to set Sun JDK as the default Java handler for your system. You need to first check the list and verify if Sun JDK is listed as an option for java handler. To see the list, execute:

This shall display a list of all the programs that can handle Java. Additionally it also displays a prompt where you can select the program that you want to be default Java handler. Each program in the list is given a number, and at the selection prompt, you just have to type the respective number. Look for something like "/opt/jdk1.6.0_17/bin/java" in the list and type its corresponding number at the prompt and press [Enter].
To check if Sun Java is the default handler, execute:

It shall display information like

This means that Sun Java is installed and being used as default Java handler.

2.3 MySQL Database Server
To install MySQL database server, we will use the yum tool. Execute at the terminal as a root user:

2.4 Install Servlet Container (Apache Tomcat Server)
Since we will be using the tomcat server included with fedora installation, we will NOT INSTALL a separate server. If you intend to use a separate server, execute the following command as root user at the terminal to install tomcat server:

2. Obtain Fedora Commons Installer
Download Fedora commons installer from the sourceforge.net project page at http://downloads.sourceforge.net/fedora-commons/. If you are planning to integrate fedora with Fez (which is a front-end to Fedora Commons), you need to choose to download version 2.2.1. The direct link to download of version 2.2.1 is http://sourceforge.net/projects/fedora-commons/files/fedora/2.2.1/fedora-2.2.1-installer.jar/download.

3. Prepare Environment Variables
Although the Environment variables are not strictly required during the time of installation, but they are required at the time of starting the fedora server. So it is always a safe point to set the environment variables before starting the installation. You need to set the following environment variables:

a) JAVA_HOME
This variable should point at the the base directory of Sun JDK installation. For this example it should be "/opt/jdk1.6.0_17/".

b) FEDORA_HOME
This variable should point at the base directory of Fedora commons installation. For this example, we will use "/var/opt/fedora/" for the installation base.

c) CATALINA_HOME
This variable should point at the base directory of the tomcat installation that is to be used with fedora commons. For this example we will use the bundled tomcat, so we will set this variable to "$FEDORA_HOME/tomcat" which means that that the tomcat base directory resides under the fedora installation directory. If you intend to use an existing tomcat, set this variable to the base directory of tomcat (e.g. "/usr/share/tomcat5")

d) JAVA_OPTS
This variable should include additional arguments to be included to make fedora run efficiently. We set the following arguments:
* Djavax.net.ssl.trustStore: The truststore location for SSL sessions (if SSL is enabled)
* Djavax.net.ssl.trustStorePassword: The truststore password
* Xmx: Allocated memory

e) PATH:
This variable should include the absolute path to the java and fedora bin directories. So we shall add "/var/opt/fedora/client/bin" and "/opt/jdk1.6.0_17/bin" to this variable.

f) CLASSPATH:
This variable should point to the Java lib directory. So we shall set this variable to "/opt/jdk1.6.0_17/jre/lib"

Now we shall create a shell script that sets these variables. The intention behind using a shell script is that it can be called any time (preferably during every fedora service start-up), so as to ensure that the environment variables are always set and point to right values. To create the script, follow these steps as a root user at the terminal:

Edit the file "fedora-profile.sh". To edit use the vim command:

Add the following lines to the file:

Save the file and exit from the vim editor.
Add executable bits to the file. Execute:

Run the script to set the environment variables. Execute:

4. Prepare Database for Fedora Commons

4.1 Start MySQL server
Check if mysqld database server is running. Execute:

If the database server is not started, start the service by executing:

To make the mysqld service start at every startup, execute:

4.2 Login to MySQL
To login to mysql, execute:

Provide the mysql's root password, and press [Enter].

4.3 Create a database for Fedora Commons
Fedora 2.x installation by default uses a database named "fedora22". So we require to create that database. Execute, at the mysql prompt,

4.4 Add the database user and grant permissions on the database
In this example we create a user named "adminFedora" and the password "adminFedora" and give all permissions to the user on the fedora database (i.e. fedora22).

4.5 Quit from the mysql prompt:

5. Install Fedora Commons

• Move to the directory where you have downloaded the installation jar file (e.g. fedora-2.2.1-installer.jar).
• To start installation, execute:
  
  java -jar fedora-2.2.1-installer.jar
• This will start the installation, during which you shall be asked several questions. For the context of this example, we shall use the predefined values as answers, which can be changed as per your requirement/choice.
• The first question would be a choice between three different modes of installation (viz. quick, custom, client). In this example, since we are trying to install a fedora commons server having custom configurations, we will choose the "custom" mode. Type "custom" at the prompt and press [Enter].
• The next question you get is the location/path of the base directory of fedora installation. If you've already set the FEDORA_HOME environment variable, the installer will display you the default value. If the default value is displayed, and you want to choose the default value, press [Enter] without typing anything; else type the full absolute path of the installation directory (e.g, /var/opt/fedora) and press [Enter].
• The next question you encounter is the password required to administer the fedora installation. It is the password of the fedora Administrative user called "fedoraAdmin". In this example we shall use the password "adminFedora". Type the password and press [Enter].
• The next question is the hostname of the fedora server. The default is "localhost". In this example, we shall use the default value, and hence press [Enter] without typing any value at the prompt.
• Then you shall be asked about the "Authentication requirement for API-A", for which we shall use the default value which is "false" and hence press [Enter].
• Next you shall be asked about "SSL Availability". For this example, we will disable SSL support, hence we will type "false" at the prompt and press [Enter].
• The next step will ask you about how to setup the servlet engine. The available options are "included", "existingTomcat", "other". The "included" option shall install the bundled tomcat into the $FEDORA_HOME directory, "existingTomcat" to use the tomcat installation that has previously been installed, "other" to use other servelet engines like "jetty". For this example, we will choose the "included" tomcat which is the default option, and hence press [Enter] at the prompt.
• Next you shall be asked about the path for tomcat installation base directory. The default option is $FEDORA_HOME/tomcat (i.e. in our example /var/opt/fedora/tomcat), if you have chosen to install the "included" tomcat bundle. We shall choose the default option, and hence press [Enter] at the prompt.
• Next you shall be asked the "Tomcat HTTP Port" that is the default NON-SSL port for fedora (the port on which tomcat will listen to). The default option is port 8080. We shall choose the default option and hence press [Enter] at the prompt.
• Next you shall be asked the "Tomcat Shutdown Port". The default option is 8005. We shall choose the default option, and hence press [Enter] at the prompt.
• Next you shall be asked about if the XACML policy should be enforced or not. The default option is "true". We shall choose the default option, and hence press [Enter] at the prompt.

The next steps will take you to the database configuration.

• At this step, you shall be asked about the database provider to use. The available options are "mckoi", "mysql", "oracle", "postgresql" and "included". For this example we shall be using Fedora Commons with MySQL database, hence we will type "mysql" at the prompt and press [Enter].
• Next you shall be asked about the database driver (JDBC driver, since we are using java). You are required to type the full absolute path of the driver. Since we shall be using the "included" JDBC driver which is also the default option, and hence we press [Enter] at the prompt.
• Next you shall be asked about the database username that would be used to connect to the database. In the previous section entitled "Prepare Database for Fedora Commons" we had setup a user name with the credentials: Username - "adminFedora", and Password - "adminFedora". Hence we shall use the same credentials. If you have used a different username, you can supply it here. Type "adminFedora" at the prompt and press [Enter].
• Next you shall be asked about the password to be used to acess the fedora database. The password should correspond to the user that we have entered in the previous step (in the example, the password of the "adminFedora" mysql user). In the example, the password is "adminFedora". Type "adminFedora" at the prompt and press [Enter].
• Next you shall be asked about the jdbc url that would be used to connect to the database. The default option is "jdbc:mysql://localhost/fedora22?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true". You should replace "fedora22" in the url with a appropriate database name, if in the previous section you have chosen to create a database (for fedora) with a different name rather than "fedora22". We shall use the default option, and hence press [Enter] at the prompt.
• Next you shall be asked about the JDBC driver class. We shall use the default option and hence press [Enter] at the prompt.

If the installer succeeds to connect to the database using the configuration values as supplied to it in the previous step, it will take you to the next configuration steps, else it will repeat the database configuration section.

• After succeeding to connect to the database, it will ask you if you want to deploy local services and demo. The demo objects are good for testing fedora installation. The default option is "true". We shall use the default option, and hence press [Enter].

It will take a while for the installer while it prepares the fedora base directory will all the essential files and directory structure, plus configuring the servlet engine and deploying local and demo applications. After performing these steps, the installer will quit giving you an clear notice that fedora have been installed and you must configure the required environment variables in order to run fedora.

6. Configure Fedora Server
Fedora Commons server comes with configuration that can be changed. The configuration file is located at "$FEDORA_HOME/server/config/fedora.fcfg" (i.e. "/var/opt/fedora/server/config/fedora.fcfg" in our example. In the example installation we shall only change a few configuration to make our task easier.

• Open the fedora.fcfg file in editor. Execute:
  
  vim $FEDORA_HOME/server/config/fedora.fcfg
• Edit the line <param name="adminEmailList" value="bob@example.org sally@example.org">, in the value part type the email address(es) of the Fedora Commons administrator. If you want to keep more than one email address, separate the entries with a .
• Edit the line <param name="ENFORCE-MODE" value="enforce-policies"/> and in the value part replace "enforce-policies" with "permit-all-requests".
• Edit the line <param name="pidNamespace" value="changeme">, in the value part, replace "changeme" with the required pidNamespace. In this example, we shall use the pidNamespace as "Pustakalaya".
• Edit the line <param name="retainPIDs" value="demo test changeme fedora-bdef fedora-bmech tutorial"> and replace "changeme" with the pidNamespace that we have chosen in the previous step. In the example, we shall replace "changeme" with "Pustakalaya".
• Save the file and exit the editor.

7. Configure the Tomcat Servlet Engine
The configuration of the tomcat servlet engine is located in a file at $CATALINA_HOME/conf/server.xml (i.e. /var/opt/fedora/tomcat/conf/server.xml in our example installation). The default configuration is well appropriate to run, but we will change a few settings to make our work easier.

• Open the server.xml file in a editor. Execute:
  
  vim $CATALINA_HOME/conf/server.xml
• Edit the line <Connector port="8080" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="true" redirectPort="8443" acceptCount="100" debug="0" connectionTimeout="20000" disableUploadTimeout="true"/> and replace enableLookups="true" with enableLookups="false".
• Save the file and exit the editor.

8. Additional configuration to set Fedora Commons as a service
This setup is optional, but is recommended since it shall make things easier. In this step we will create a shell script that will interact with the standard "service" command, and helps us to start, stop, check status, reload fedora commons server. To create the script, follow these steps:

• cd /etc/init.d/
• touch fedora
  chmod 755 fedora
• Edit the file in the editor. Execute:
  
  vim fedora
• Add these lines in the file:
  
  #!/bin/sh
  #
  # fedora commons database
  #
  # chkconfig:   - 20 80
  # description: Fedora commons content library
  
  ### BEGIN INIT INFO
  # Provides: fedora
  # Required-Start: mysqld
  # Required-Stop: mysqld
  # Short-Description: Fedora commons content library
  # Description: Fedora commons content library
  ### END INIT INFO
  
  . /etc/profile.d/fedora-profile.sh
  export CATALINA_PID=/tmp/fedora-catalina.pid
  
  # determines if Fedora is running by examining the command line of a certain
  # pid.
  # args: <suspected pid of Fedora>
  fedora_alive()
  {
          [ -d /proc/"$1" ] || return 1
          cmd=$(ps -p "$1" -o command=)
          [ $? == 0 ] || return 1
          [[ "${cmd}" =~ ".*java.*fedora.*tomcat.* start$" ]]
  }
  
  status()
  {
          [ -e "$CATALINA_PID" ] || return 3
          local pid=$(<$CATALINA_PID)
          fedora_alive $pid || return 3
          echo "Fedora running at pid $pid"
  }
  
  start()
  {
          local pid=""   
          [ -e $CATALINA_PID ] && pid=$(<$CATALINA_PID)
          if [ -n "$pid" ] && fedora_alive $pid; then
                  echo "Can't start, Fedora already running as pid $pid"
                  return 1
          fi
  
          # reset working directory, because the java process takes a handle on
          # the directory from where this init script was ran
          cd /
  
          /var/opt/fedora/tomcat/bin/startup.sh  
  }
  
  stop()
  {
          local pid=$(<$CATALINA_PID)
          /var/opt/fedora/tomcat/bin/shutdown.sh >/dev/null 2>&1
          retval=$?
          if [ $retval -eq 0 ]
          then
                  echo "Fedora shutting down."
          fi
          sleep 3
          [ -z "${pid}" ] && return $?
  
          for i in $(seq 0 10); do
                  fedora_alive $pid || return 0
  
                  echo "Fedora shutdown failed, retry in 5 secs"
                  sleep 5
                  /var/opt/fedora/tomcat/bin/shutdown.sh >/dev/null 2>&1
          done
          fedora_alive $pid || return 0
          echo "Force kill Fedora."
          kill ${pid}
          sleep 5
          fedora_alive || return 0
          kill -9 ${pid}
  }
  
  case "$1" in
          start) start ;;
          stop) stop ;;
          restart) stop; start ;;
          status) status ;;
          *)
          echo $"Usage: $0 {start|stop|status|restart|condrestart|try-restart|reload|force-reload}"
          exit 2
  esac
  exit $?
• save the file and exit editor.

9. Start fedora service
To start the fedora service, you can now execute:

10. Test Fedora Commons
10.1 Test if MySQL Service is running

Start the service if it has not yet started by executing:

10.2 Test if Fedora Commons is running

Start the service if it is not yet started by executing:

10.3 Test tomcat servlet engine
Open a browser and browse http://localhost:8080. If the page displays Apache Tomcat Start page, this means the tomcat servlet engine is running.
Now browse to http://localhost:8080/fedora. It shall ask you the login credentials. Provide user-name as "fedoraAdmin" and password as "adminFedora". Remember to use the password that we have supplied during the section "Install Fedora Commons". After logging in, you shall see the "Apache-AXIS" page. This means that the fedora service is running well.

11. Further test with demo objects
This step is optional, but can be performed to see if fedora commons is behaving appropriately by storing objects, datastreams, and their metadata, as well as to check if it provides interface to retrieve and update those objects. To do this, we need to ingest the demo objects to the fedora server. Follow these steps:

• Ensure that all the required services and daemons and running.
• Open a terminal and follow these steps:
  
  cd $FEDORA_HOME/client/bin/
  fedora-ingest-demos.sh localhost 8080 fedoraAdmin fedoraAdmin http
• This step will ingest the demo objects to the fedora commons repository. To check the demo objects, open a browser and browse http://localhost:8080/fedora/get/demo:5. If it displays the page with the description of the demo object, this means that fedora is working correctly.
• The repository objects can be tested with the fedora GUI client as well.
• Open a terminal and follow these steps:
  
  cd $FEDORA_HOME/client/bin/
  ./fedora-admin.sh
  
  Type the password for the user "fedoraAdmin", i.e. "adminFedora" in our example. Now you can use the UI for searching of objects, adding new objects to the repository and other actions.

Attachment	Size
fedora	1.86 KB
fedora-profile.sh	430 bytes

• aks's blog