you're reading...


Fedora Commons Installation and Configuration Guide


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


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


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:
    		sh 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.
    cp -a jdk1.6.0.7_17/ /opt/
    chmod -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:
    alternatives --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:
    alternatives --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:

    java -version

    It shall display information like:

    java version "1.6.0_17"
    Java(TM) SE Runtime Environment (build 1.6.0_17-b08)
    Java 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:

yum -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:

yum -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:


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


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.


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


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


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.


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:

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

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

vim fedora-profile.sh

Add the following lines to the file:

JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=$FEDORA_HOME/server/truststore"
JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStorePassword=tomcat"

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

chmod 755 fedora-profile.sh

Run the script to set the environment variables. Execute:

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

Prepare Database for Fedora Commons

Start MySQL server

Check if mysqld database server is running. Execute:

service mysqld status

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

service mysqld start

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

chkconfig mysqld on

Login to MySQL

To login to mysql as root user, execute:

mysql -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:

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

GRANT ALL ON fedora22.* TO adminFedora@localhost IDENTIFIED BY 'adminFedora';

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:
    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”. 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:
    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 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:
    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.

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:
    touch /etc/init.d/fedora
  • Edit the file in the editor. Execute:
    vim /etc/init.d/fedora
  • Add these lines in the file:
    # fedora commons database
    # chkconfig:   - 20 80
    # description: Fedora commons content library
    # Provides: fedora
    # Required-Start: mysqld
    # Required-Stop: mysqld
    # Short-Description: Fedora commons content library
    # Description: Fedora commons content library
    . /etc/rc.d/init.d/functions
    . /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>
    #echo $1
    [ -d /proc/"$1" ] || return 1
    cmd=$(ps -p "$1" -o command=)
    [ $? == 0 ] || return 1
    [[ "${cmd}" =~ ".*java.*fedora.*tomcat.* start$" ]]
    echo $?
    [ -e "$CATALINA_PID" ] || return 3
    local pid=$(<$CATALINA_PID)
    #fedora_alive $pid || return 3
    #echo "Fedora running at pid $pid"
    fedora_alive $pid && rt=0 || rt=3
    if [ $rt -eq 0 ]
    echo "Fedora Commons service is running at pid $pid"
    echo "Fedora Commons service is stopped."
    return $rt
    local pid=""
    [ -e $CATALINA_PID ] && pid=$(<$CATALINA_PID)
    if [ -n "$pid" ] && fedora_alive $pid; then
    echo "Fedora Commons service already running as pid $pid"
    return 1
    # 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 > /dev/null
    if [ $? -eq 0 ]
    action "Starting Fedora Commons Service: " /bin/true
    action "Starting Fedora Commons Service: " /bin/false
    local pid=$(<$CATALINA_PID)
    /var/opt/fedora/tomcat/bin/shutdown.sh > /dev/null 2>&1
    if [ $retval -eq 0 ]
    action "Stopping Fedora Commons Service: " /bin/true
    action "Stopping Fedora Commons Service: " /bin/false
    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
    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}"
    exit 2
    exit $?
  • Save the file and exit editor.
  • Set proper permissions.
chmod 755 /etc/init.d/fedora

Start fedora service

To start the fedora service, you can now execute:

service fedora start

Test Fedora Commons

Test if MySQL Service is running

service mysqld status

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

service mysqld start

Test if Fedora Commons is running

service fedora status

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

service fedora start

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

chkconfig --add fedora
chkconfig 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:
    cd $FEDORA_HOME/client/bin/
    fedora-ingest-demos.sh localhost 8080 fedoraAdmin adminFedora 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/

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.


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


    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.


        Posted by Prasad | January 26, 2012, 9:56 pm
  3. I would like to develop servlet program in fedora17 in which jdk7 is installed. It is asking me to set the classpath to servlet-api.jar. But i don’t know the way to set. Please can anyone help me?

    Posted by RADHAKRISHNA | September 8, 2012, 2:32 pm
  4. Isn’t there something wrong with the startscript?

    When I start fedora it does start, but when I run “service fedora status” it returns that it is stopped though it is not.

    Posted by Paul Bergstrom | October 17, 2012, 12:59 am
  5. Whn i do chkconfig fedora on. and reboot Centos fedora service starts for few seconds – when i check service fedora status it returns 1. Few seconds later when i check status it is stopped. Any ideas?

    Posted by Man | January 14, 2013, 7:29 pm
  6. When I paste the script from the “Set Fedora Commons as a Service” in my VIM editor, there are a few places where the syntax is not correct. Or at least when I look at the script in my vim editor, there are spots in the script that are colored in a red background (which from my limited experience means that the syntax there is incorrect).

    The syntax problem repeats through the script with the following construction: $(ps -p “:$1” -o command=)

    Wherever there is a followed by a paranthesis, there is a red background around the and the parantheses.See lines 28, 37, 53, 74, and 86.

    Now, it could be that there’s nothing wrong with the script, and for some unknown reason the VIM editor is placing that $(…) in red.

    But when I go to start the Fedora Commons Service, it fails.

    Posted by Nathan pease | June 26, 2014, 6:44 am
    • In my third paragraph, it should read “Wherever there is a $ followed by a paranthesis, there is a red background around the $ and the parantheses.”

      Posted by Nathan pease | June 26, 2014, 6:46 am
      • Hi Nathan,
        Vim will syntax highlight for shell scripts in red/pink whatever is enclosed in $(). So it is okay. I’ve tested this start script myself and it worked. I had this tested on Fedora 13. Can you please provide the log which shows that the service failed (fpaste) along with the screenshot (if any)?

        Posted by Abhishek Singh | June 26, 2014, 11:44 am
        • Abhishek,

          Thank you for your response. It’s been quite some time since you last posted on here. Thank you again.

          As I am such a Linux newbie, I am going back to a clean install of CentOS and then building up again. Unfortunately, that’s the best way I learn: The more I do it, the better I understand what I’m doing. In the best of all possible worlds, you won’t hear from me again, because it will all work.

          I am a librarian and am very much interested in Fedora Commons as well as the data conservancy.

          Take care!

          Posted by Nathan Pease | June 27, 2014, 11:57 pm


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

  2. […] You’d want to start with the Islandora wiki for both installation instructions and answers as to what Islandora is and what it can do; there’s also the main Islandora site. Other places to look for help include the main Islandora listerv for Islandora users, the Islandora Dev listserv (if you’re looking for help in developing on Islandora), and listservs for any particular pieces of the installation process that give you trouble (e.g. I found the Fedora Commons developer mailing list and the Adore Djatoka wiki helpful, as well as this blog post on Fedora set-up). […]

Post a Comment