//
you're reading...

Blog

Fedora Commons Installation and Configuration Guide

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.

Introdution

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)

Install Prerequisites

Sun Java Development Kit (JDK)

  1. 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 *.bin version to download.
  2. After downloading, as a root user execute:
    1sh jdk*.bin
  3. 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.
  4. This shall create a directory in the current location in the format jdk1.6.0.7_17. Copy the whole directory to /opt and set 755 permission on it.
    1cp -a jdk1.6.0.7_17/ /opt/
    2chmod -R 755 /opt/jdk1.6.0.7_17/
  5. Next, you need to set Sun JDK as the default Java handler for your system. To install Sun’s JDK as the default, execute:
    1alternatives --install /usr/bin/java java /opt/jdk1.6.0.7_17/bin/java 20000
  6. 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:
    1alternatives --config java

    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:

    1java -version

    It shall display information like:

    1java version "1.6.0_17"
    2Java(TM) SE Runtime Environment (build 1.6.0_17-b08)
    3Java HotSpot(TM) Server VM (build 17.0-b16, mixed mode)

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

MySQL Database Server

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

1yum -y install mysql mysql-server mysql-connector-java mysql-connector-odbc mysql-libs

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:

1yum -y install tomcat5 tomcat5-webapps tomcat5-admin-webapps

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.

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:

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/.

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.

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″).

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

PATH

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

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:

1cd /etc/profile.d/
2touch fedora-profile.sh

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

1vim fedora-profile.sh

Add the following lines to the file:

1FEDORA_HOME=/var/opt/fedora
2JAVA_HOME=/opt/jdk1.6.0_17/
3CLASSPATH=$JAVA_HOME/jre/lib
4CATALINA_HOME=/var/opt/fedora/tomcat/
5JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=$FEDORA_HOME/server/truststore"
6JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStorePassword=tomcat"
7JAVA_OPTS="$JAVA_OPTS -Xmx512m"
8PATH="$PATH:$FEDORA_HOME/server/bin:$FEDORA_HOME/client/bin"
9export JAVA_HOME CLASSPATH CATALINA_HOME JAVA_OPTS FEDORA_HOME PATH

Save the file and exit from the vim editor. Also set executable permission to the file:

1chmod 755 fedora-profile.sh

Run the script to set the environment variables. Execute:

1sh fedora-profile.sh
2source /etc/profile.d/fedora-profile.sh

Prepare Database for Fedora Commons

Start MySQL server

Check if mysqld database server is running. Execute:

1service mysqld status

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

1service mysqld start

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

1chkconfig mysqld on

Login to MySQL

To login to mysql as root user, execute:

1mysql -u root -p

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

Create a database for Fedora Commons

Fedora 2.2 installation by default uses a database named “fedora22″. So we require to create that database. Execute, at the mysql prompt:

1CREATE DATABASE fedora22 default charset utf8;

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).

1GRANT ALL ON fedora22.* TO adminFedora@localhost IDENTIFIED BY 'adminFedora';
2FLUSH PRIVILEGES;

Quit from the mysql prompt.

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:
    1java -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”. Hence type adminFedora 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. If the default installation base is not displayed, you’ll need to type the path manually and press [Enter].
  • 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 database 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.

Configure Fedora Server

Fedora Commons server comes with configuration file that can be changed to tweak its behaviour. 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:
    1vim $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 space.
  • 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.

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:
    1vim $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.

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:

  • Create the service script. Execute:
    1touch /etc/init.d/fedora
  • Edit the file in the editor. Execute:
    1vim /etc/init.d/fedora
  • Add these lines in the file:
    1#!/bin/sh
    2#
    3# fedora commons database
    4#
    5# chkconfig:   - 20 80
    6# description: Fedora commons content library
    7 
    8### BEGIN INIT INFO
    9# Provides: fedora
    10# Required-Start: mysqld
    11# Required-Stop: mysqld
    12# Short-Description: Fedora commons content library
    13# Description: Fedora commons content library
    14### END INIT INFO
    15 
    16. /etc/rc.d/init.d/functions
    17. /etc/profile.d/fedora-profile.sh
    18 
    19export CATALINA_PID=/tmp/fedora-catalina.pid
    20 
    21# determines if Fedora is running by examining the command line of a certain
    22# pid.
    23# args: <suspected pid of Fedora>
    24fedora_alive()
    25{
    26#echo $1
    27[ -d /proc/"$1" ] || return 1
    28cmd=$(ps -p "$1" -o command=)
    29[ $? == 0 ] || return 1
    30[[ "${cmd}" =~ ".*java.*fedora.*tomcat.* start$" ]]
    31echo $?
    32}
    33 
    34status()
    35{
    36[ -e "$CATALINA_PID" ] || return 3
    37local pid=$(<$CATALINA_PID)
    38#fedora_alive $pid || return 3
    39#echo "Fedora running at pid $pid"
    40fedora_alive $pid && rt=0 || rt=3
    41if [ $rt -eq 0 ]
    42then
    43echo "Fedora Commons service is running at pid $pid"
    44else
    45echo "Fedora Commons service is stopped."
    46fi
    47return $rt
    48}
    49 
    50start()
    51{
    52local pid=""
    53[ -e $CATALINA_PID ] && pid=$(<$CATALINA_PID)
    54if [ -n "$pid" ] && fedora_alive $pid; then
    55echo "Fedora Commons service already running as pid $pid"
    56return 1
    57fi
    58 
    59# reset working directory, because the java process takes a handle on
    60# the directory from where this init script was ran
    61cd /
    62 
    63/var/opt/fedora/tomcat/bin/startup.sh > /dev/null
    64if [ $? -eq 0 ]
    65then
    66action "Starting Fedora Commons Service: " /bin/true
    67else
    68action "Starting Fedora Commons Service: " /bin/false
    69fi
    70}
    71 
    72stop()
    73{
    74local pid=$(<$CATALINA_PID)
    75/var/opt/fedora/tomcat/bin/shutdown.sh > /dev/null 2>&1
    76retval=$?
    77if [ $retval -eq 0 ]
    78then
    79action "Stopping Fedora Commons Service: " /bin/true
    80else
    81action "Stopping Fedora Commons Service: " /bin/false
    82fi
    83sleep 3
    84[ -z "${pid}" ] && return $?
    85 
    86for i in $(seq 0 10); do
    87fedora_alive $pid || return 0
    88 
    89echo "Fedora shutdown failed, retry in 5 secs"
    90sleep 5
    91/var/opt/fedora/tomcat/bin/shutdown.sh > /dev/null 2>&1
    92done
    93fedora_alive $pid || return 0
    94echo "Force kill Fedora."
    95kill ${pid}
    96sleep 5
    97fedora_alive || return 0
    98kill -9 ${pid}
    99}
    100 
    101case "$1" in
    102start) start ;;
    103stop) stop ;;
    104restart) stop; start ;;
    105status) status ;;
    106*)
    107echo $"Usage: $0 {start|stop|status|restart}"
    108exit 2
    109esac
    110exit $?
  • Save the file and exit editor.
  • Set proper permissions.
1chmod 755 /etc/init.d/fedora

Start fedora service

To start the fedora service, you can now execute:

1service fedora start

Test Fedora Commons

Test if MySQL Service is running

1service mysqld status

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

1service mysqld start

Test if Fedora Commons is running

1service fedora status

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

1service fedora start

You can also set the Fedora Commons service to automatically start at startup. Execute:

1chkconfig --add fedora
2chkconfig fedora on

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.

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:
    1cd $FEDORA_HOME/client/bin/
    2fedora-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:
1cd $FEDORA_HOME/client/bin/
2./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.

Enjoy using the Fedora Commons data repository.

Discussion

5 Responses to “Fedora Commons Installation and Configuration Guide”

  1. This is really an excellent work.
    I can continue with my research on building a custom solution for fedora.

    Posted by Uchechukwu Onuoha | October 1, 2011, 7:39 pm
  2. This all works fine on the linux box where the fedora was installed i.e. when I type http://localhost:8080/fedora or http://ipaddress:8080/fedora. But when I try to open the url from a client machine like windows xp, in firefox this is what I get
    The server at ipaddress is taking too long to respond.

    I am not sure where I went wrong. I will appreciate your help on resolving this issue.

    Thanks,
    Prasad

    Posted by Prasad | January 25, 2012, 11:47 pm
    • Hi Prasad,
      This means that fedora is running on the machine (which is verified by being able to open the link on the local machine). There might be various reasons for not being able to open the link on client machines. Some of the reasons and their solution are as below:
      1. The firewall (iptables) might be blocking access to the 8080 port. To resolve this, please execute on terminal “sudo iptables -I INPUT -p tcp –dport 8080 -j ACCEPT”. If this solves your problem, you might want to save this rule (as it will be discarded on reboot) by executing “sudo service iptables save”.
      2. There might be problem with your network and the packets originating from the client might be unable to reach fedora server. Please confirm that the network is working by pinging the server (command: ping ).

      Hope this helps.

      Posted by Abhishek Singh | January 26, 2012, 9:28 am
      • Abhishek,

        Thank you for your prompt response. That didn’t strike my mind, I did enable port 80 on the firewall but didn’t realize I have to enable port 8080 also. That worked. Thanks once again.

        Prasad.

        Posted by Prasad | January 26, 2012, 9:56 pm

Trackbacks/Pingbacks

  1. [...] See the installation instructions. [...]

Post a Comment