Installing LON-CAPA on a Fedora Core 2 Linux System

This document guides you through the process of setting up a new LON-CAPA server running Fedora Core 2 (FC2). The computer will be configured solely as a LON-CAPA server and will be expected to have no other services running on it.

More information is available at http://install.lon-capa.org/.

Before you begin

Installing Linux is getting easier and easier. However, it is still a non-trivial undertaking and experience with Red Hat Linux will make this process easier. You will be required to log in to the machine and execute some routine Unix commands. Some familiarity with Linux is assumed. Familiarity with the Apache web server, mod_perl, perl, and MySQL are not required to install and run LON-CAPA.

Installation Overview

The installation process takes the following steps:

  1. Obtain Fedora Linux
  2. Determine Network Settings
  3. Install Fedora
  4. Uninstall the http server
  5. Install LON-CAPA Dependencies
  6. Determine your LON-CAPA Settings
  7. Install LON-CAPA
  8. Configure LON-CAPA
  9. Pick a hosts.tab file
  10. Create a Domain Coordinator
  11. Start/Restart services
  12. Log in to LON-CAPA

Obtain Fedora Linux

Fedora linux ISO files can be obtained from the projects main site, http://fedora.redhat.com/.

Determine Network Settings

You will need to know the following network settings for your installation. Note:You must have a static IP address to use LON-CAPA. DHCP is not supported.

Install Fedora

Installing Fedora is quite easy if you've installed any of the Red Hat products before. Some documentation is available from http://fedora.redhat.com/projects/anaconda-installer/. There are a few sections that require comment.

Installation Type
You should do a "Server" install. We do not recommend trying to install LON-CAPA with a different installation type.
Partitioning your Drive
You may want to use the automatic partitioning feature of the installer, however you should review the results and be prepared to modify them. LON-CAPA resource files are stored in the /home directory, so the lion's share of the drive should be allocated here. If you have 20 GB of space for Red Hat, /home should receive at least 10 to 12 gigs. Since MySQL uses the /var filesystem to store its databases you should have at least 4 gigs of space available on /var. Be sure to include adequate swap space. A minimum is 512 Megs, but you should typically have 1 or 2x as much swap space as you do physical RAM.
Network Configuration
LON-CAPA will not work with a machine set up to use a dynamic IP address. When configuring your network card, be sure to unselect the DHCP option and enter in your network information.
Firewall Configuration
The firewall should be customized to allow incoming ssh and www. Additional ports used by LON-CAPA are 5663 and 8080. Enter these in the entry box as "5663:tcp, 8080:tcp".
Package Group Selection
Do not install a web server. It is intentially omitted from this list. Installing packages not listed below is not recommended. If you install packages not listed below you should expect difficulties when installing the LON-CAPA dependencies.

Finish installing your server, reboot it, and log in as root.

Retrieving the LON-CAPA Installation Archive

Execute the following command: 

wget http://install.loncapa.org/versions/fedora/fedora_install.tar

This will retrieve from the LON-CAPA website all the packages needed to get LON-CAPA running on your system, except for the LON-CAPA source itself.

Extract the archive with the following command: 

tar xf fedora_install.tar

This creates a directory named installation.

Uninstall the http server

Fedora Core 2 installs the http server even if you have not chosen it in the package selection part of the install. LON-CAPA will not work with this web server installed. It must be removed. Use the following commands to remove the http and mod_perl packages if they exist: (Note: The commands below use backticks, not single quotes.: 

rpm -e `rpm -q -a | grep mod_perl`
rpm -e `rpm -q -a | grep httpd`

If the above commands returns no output (the usual indicator of success), or an error message 'rpm: no packages given for erase' (meaning there were no packages that contain httpd or mod_perl), you are good to go.

Installing LON-CAPA Dependencies

This section walks you through installing the packages which LON-CAPA requires. There are a lot of dependencies. They have been grouped in a somewhat logical fashion to make them easier to deal with. When installing the rpms you should watch for errors. Errors generated by RPMs which are already should not be considered a problem, although you will have to ensure the other rpms in the directory get installed.

To install the many LON-CAPA dependencies, execute the following commands: 

cd installation
cd mysql
rpm -Uvh *rpm
cd ../apache
rpm -Uvh *rpm
cd ../mod_perl
rpm -Uvh *rpm
cd ../perl_dependencies
rpm -Uvh *rpm
cd ../GD
rpm -Uvh *rpm
cd ../gnuplot
rpm -Uvh *rpm
cd ../misc
rpm -Uvh *rpm
cd ..

Notes:

Configuring LON-CAPA Dependencies

We have prepared a script which takes care of most of the configuration that must be done to get the newly installed packages working with LON-CAPA. This script will retrieve the latest LON-CAPA release from http://install.loncapa.org. You will be prompted for a root password for your MySQL server. You will need to remember this password in case you should ever need to make changes the the server.

Execute the script as follows: 

cd setup;
./install.pl

Determine LON-CAPA Settings

LON-CAPA requires a number of identifying parameters be set in order for it to function at all. Below is a list with descriptions.

Host Type (library or access)
The server must be designated a 'library' or an 'access' server. In general you should have a library server for your instructors to create their course content on and run their courses. Students should connect to access servers. If you are doing the first install of LON-CAPA at your site, or if you are playing with it for your own edification you should make your machine a 'library' server.
LON-CAPA domain
Each site or school which installs LON-CAPA needs its own domain. Here at MSU we use 'msu'. You should choose something short but meaningful. Restriction: One word, no hyphens, underscores, or special characters.
LON-CAPA host id
Each LON-CAPA server requires a unique internal name. We use names such as "msul1" for the first library server. Restriction: One word, no hyphens, underscores, or special characters.
Host administrator email
The amount of email sent to this address is relatively minimal. Messages are sent every time the system starts up, or if the system is in serious trouble. On a laptop, make this root@localhost.

Configuring LON-CAPA

To configure and install LON-CAPA, execute the following commands: 

cd /root/loncapa-N.N     (N.N should correspond to a version number like '1.2')
./UPDATE

You will need to enter the LON-CAPA configuration information you determined in the previous section.

Creating a Domain Coordinator

You will need at least one user at your site who has the role of 'domain coordinator'. This user creates accounts for other users and grants them additional privileges. The make_domain_coordinator.pl script invoked below requires that you enter the users password. The password will show in plaintext as you type it. Feel free to use the "passwd username" command to change it later. Replace USERNAME and DOMAIN with an appropriate user name and your domain. 

cd /root/loncapa-N.N/loncom/build
perl make_domain_coordinator.pl USERNAME DOMAIN
(WILL PROMPT FOR PASSWORD HERE)
mkdir ~USERNAME/public_html
chown USERNAME:www ~USERNAME/public_html
chmod 0775 ~USERNAME/public_html
chmod a+x ~USERNAME

Start/Restart Services

The LON-CAPA network services take a moment to start. Most misconfigurations will be appearant at this step. 

/etc/init.d/loncontrol start
/etc/init.d/httpd start

If you receive warnings when starting the httpd about missing perl modules, please make sure you followed the instructions in Installing LON-CAPA Dependencies. If you still have errors, please contact the LON-CAPA development team.

Log in to your LON-CAPA Machine

Point a web browser at your new machine and log in as the domain coordinator. Congratulations!

If Things aren't working right

If you've followed the steps above and the server doesn't start or you think there's something wrong, please get in touch with the LON-CAPA developers. If there were errors in installation of the dependency RPMs or during the automatic setup, please send us as much information as possible. If some part of this document is unclear please let us know.