Annotation of doc/build/fedora_install.frag, revision 1.11

1.5       matthew     1: <h1>Installing LON-CAPA on a Fedora Core 2 Linux System</h1>
1.1       matthew     2: <p>
                      3: This document guides you through the process of setting up a new LON-CAPA
1.5       matthew     4: server running Fedora Core 2 (FC2).  The computer will be configured solely as
1.1       matthew     5: a LON-CAPA server and will be expected to have no other services running
                      6: on it.
                      7: </p><p>
                      8: More information is available at <a href="http://install.lon-capa.org/">
                      9: http://install.lon-capa.org/</a>.
                     10: </p>
                     11: 
                     12: <h2>Before you begin</h2>
                     13: <p>
                     14: Installing Linux is getting easier and easier.  However, it is still a
                     15: non-trivial undertaking and experience with Red Hat Linux will make this 
                     16: process easier.  You will be required to log in to the machine and execute
                     17: some routine Unix commands.  Some familiarity with Linux is assumed.  
                     18: Familiarity with the Apache web server, mod_perl, perl, and MySQL are not 
                     19: required to install and run LON-CAPA.
                     20: </p>
                     21: 
                     22: <h2>Installation Overview</h2>
                     23: <p>
                     24: The installation process takes the following steps:
                     25: </p>
                     26: <ol>
                     27:   <li> Obtain Fedora Linux </li>
                     28:   <li> Determine Network Settings</li>
                     29:   <li> Install Fedora </li>
1.7       matthew    30:   <li> Uninstall the http server </li>
1.1       matthew    31:   <li> Install LON-CAPA Dependencies </li>
                     32:   <li> Determine your LON-CAPA Settings </li>
                     33:   <li> Install LON-CAPA </li>
                     34:   <li> Configure LON-CAPA </li>
                     35:   <li> Pick a hosts.tab file </li>
                     36:   <li> Create a Domain Coordinator </li>
                     37:   <li> Start/Restart services </li>
                     38:   <li> Log in to LON-CAPA </li>
                     39: </ol>
                     40: 
                     41: <h2>Obtain Fedora Linux</h2>
                     42: <p>
                     43: Fedora linux ISO files can be obtained from the projects main site,
                     44: <a href="http://fedora.redhat.com/">http://fedora.redhat.com/</a>.
                     45: </p>
                     46: 
                     47: <h2>Determine Network Settings</h2>
                     48: <p>
                     49: You will need to know the following network settings for your installation.  
                     50: <b>Note:</b>You must have a static IP address to use LON-CAPA.
                     51: DHCP is <em>not</em> supported.
                     52: </p>
                     53: <ul>
                     54:   <li>ip address </li>
                     55:   <li>netmask </li>
                     56:   <li>hostname </li>
                     57:   <li>gateway </li>
                     58:   <li>domain name server(s) </li>
                     59: </ul>
                     60: 
                     61: <h2>Install Fedora</h2>
                     62: <p>
                     63: Installing Fedora is quite easy if you've installed any of the Red Hat products
                     64: before.  Some documentation is available from 
                     65: <a href="http://fedora.redhat.com/projects/anaconda-installer/">
                     66: http://fedora.redhat.com/projects/anaconda-installer/</a>.
                     67: There are a few sections that require comment.
                     68: </p>
                     69: <dl style="list-style:square outside none">
                     70:    <dt>Installation Type</dt>
                     71:    <dd>You should do a "Server" install.  We do not recommend
                     72:        trying to install LON-CAPA with a different installation type.</dd>
                     73:    <dt>Partitioning your Drive</dt>
                     74:    <dd>You may want to use the automatic partitioning feature of the installer,
                     75:        however you should review the results and be prepared to modify them.
                     76:        LON-CAPA resource files are stored in the /home directory, so the
                     77:        lion's share of the drive should be allocated here.  If you have 20 GB 
1.2       matthew    78:        of space for Red Hat, /home should receive at least 10 to 12 gigs.  
                     79:        Since MySQL uses the /var filesystem to store its databases you should
                     80:        have at least 4 gigs of space available on /var.  Be sure to 
1.1       matthew    81:        include adequate swap space.  A minimum is 512 Megs, but you should
                     82:        typically have 1 or 2x as much swap space as you do physical RAM.</dd>
                     83:    <dt>Network Configuration</dt>
                     84:    <dd>LON-CAPA will <b>not</b> work with a machine set up to use a dynamic 
                     85:        IP address.  When configuring your network card, be sure to unselect
                     86:        the DHCP option and enter in your network information.</dd>
                     87:    <dt>Firewall Configuration</dt>
                     88:    <dd>The firewall should be customized to allow incoming ssh and www.  
                     89:        Additional ports used by LON-CAPA are 5663 and 8080.  
                     90:        Enter these in the entry box as <nobr>"5663:tcp, 8080:tcp"</nobr>.</dd>
                     91:    <dt>Package Group Selection</dt>
                     92:    <dd>
                     93:        <b>Do not</b> install a web server.  It is intentially omitted from
                     94:        this list.  Installing packages not listed below is not recommended.
                     95:        If you install packages not listed below you should expect difficulties
                     96:        when installing the LON-CAPA dependencies.
                     97:       <ul>
                     98:          <li>Editors</li>
                     99:          <li>Text Based Internet</li>
                    100:          <li>Authoring and Publishing</li>
1.5       matthew   101:          <li>Server Configuration Tools</li>
1.4       matthew   102:          <li>Development Tools</li>
                    103:          <li>Administration Tools</li>
                    104:          <li>Printing Support</li>
1.1       matthew   105:       </ul>
                    106:    </dd>
                    107: </dl>
                    108: <p>
                    109: Finish installing your server, reboot it, and log in as root.
                    110: </p>
                    111: 
                    112: <h2>Retrieving the LON-CAPA Installation Archive</h2>
                    113: <p>
                    114: Execute the following command:
                    115: </p>
                    116: <pre>
                    117: wget http://install.loncapa.org/versions/fedora/fedora_install.tar
                    118: </pre>
                    119: <p>
                    120: This will retrieve from the LON-CAPA website all the packages needed to get
                    121: LON-CAPA running on your system, except for the LON-CAPA source itself.
                    122: </p>
                    123: <p>
                    124: Extract the archive with the following command:
                    125: </p>
                    126: <pre>
                    127: tar xf fedora_install.tar
                    128: </pre>
                    129: <p>
                    130: This creates a directory named <tt>installation</tt>.
                    131: </p>
                    132: 
1.6       matthew   133: <h2>Uninstall the http server</h2>
                    134: <p>
                    135: Fedora Core 2 installs the http server even if you have not chosen it in
                    136: the package selection part of the install.  LON-CAPA will not work with this
                    137: web server installed.  It must be removed.
                    138: Use the following commands to remove the http and mod_perl packages if they 
                    139: exist:  (<b>Note:</b>
                    140: <i>The commands below use backticks, not single quotes.</i>:
                    141: </p>
                    142: <p>
1.5       matthew   143: <pre>
1.9       matthew   144: rpm -e `rpm -q -a | grep mod_perl`
1.5       matthew   145: rpm -e `rpm -q -a | grep httpd`
                    146: </pre>
                    147: </p><p>
                    148: If the above commands returns no output (the usual indicator of success), or an
                    149: error message 'rpm: no packages given for erase' (meaning there were no
                    150: packages that contain httpd or mod_perl), you are good to go.  
1.7       matthew   151: </p>
                    152: 
                    153: <h2>Installing LON-CAPA Dependencies</h2>
                    154: <p>
                    155: This section walks you through installing the packages which LON-CAPA requires.
                    156: There are a lot of dependencies.  They have been grouped in a
                    157: somewhat logical fashion to make them easier to deal with.  When installing
                    158: the rpms you should watch for errors.  Errors generated by RPMs which are 
                    159: already should not be considered a problem, although you will have to ensure 
                    160: the other rpms in the directory get installed.
                    161: </p>
                    162: 
                    163: <p>
1.5       matthew   164: To install the many LON-CAPA dependencies, execute the following commands:
1.1       matthew   165: </p>
                    166: <pre>
                    167: cd installation
                    168: cd mysql
                    169: rpm -Uvh *rpm
                    170: cd ../apache
                    171: rpm -Uvh *rpm
                    172: cd ../mod_perl
                    173: rpm -Uvh *rpm
                    174: cd ../perl_dependencies
                    175: rpm -Uvh *rpm
                    176: cd ../GD
                    177: rpm -Uvh *rpm
                    178: cd ../gnuplot
1.10      matthew   179: rpm -Uvh *rpm
1.1       matthew   180: cd ../misc
                    181: rpm -Uvh *rpm
                    182: cd ..
                    183: </pre>
                    184: <p>
                    185: <b>Notes:</b>
                    186: <ul>
                    187:     <li>MySQL is used to store caches of data, not original copies.  
                    188:         Administering LON-CAPA machines does not yet mean becoming a 
                    189:         database administrator.</li>
                    190:     <li>Apache 1.3 and mod_perl 1.x are required by LON-CAPA.  These are
1.5       matthew   191:         provided in the installation package.  The mod_perl package has been
                    192:         repackaged from the Redhat sources with the name 'mod_perl_1' in
                    193:         order to prevent version 1.99 of mod_perl from being installed by 
                    194:         yum or other package managers.</li>
1.1       matthew   195: </ul>
                    196: </p>
                    197: 
                    198: <h2>Configuring LON-CAPA Dependencies</h2>
                    199: <p>
                    200: We have prepared a script which takes care of most of the configuration that
                    201: must be done to get the newly installed packages working with LON-CAPA.  
                    202: This script will retrieve the latest LON-CAPA release from
                    203: <a href="http://install.loncapa.org">http://install.loncapa.org</a>.
                    204: You will be prompted for a root password for your MySQL server.  You 
                    205: will need to remember this password in case you should ever need to make
                    206: changes the the server.
                    207: </p><p>
                    208: Execute the script as follows:
                    209: </p>
                    210: <pre>
                    211: cd setup;
                    212: ./install.pl
                    213: </pre>
                    214: 
                    215: <h2>Determine LON-CAPA Settings</h2>
                    216: <p>
                    217: LON-CAPA requires a number of identifying parameters be set in order
                    218: for it to function at all.  Below is a list with descriptions.
                    219: </p>
                    220: <dl>
                    221:   <dt>Host Type (library or access)</dt>
                    222:   <dd>The server must be designated a 'library' or an 'access' server.  In
                    223:       general you should have a library server for your instructors to create
                    224:       their course content on and run their courses.  Students should connect
                    225:       to access servers.  If you are doing the first install of LON-CAPA at 
                    226:       your site, or if you are playing with it for your own edification you
                    227:       should make your machine a 'library' server.</dd>
                    228:   <dt>LON-CAPA domain</dt>
                    229:   <dd>Each site or school which installs LON-CAPA needs its own domain.
                    230:       Here at MSU we use 'msu'.  You should choose something short but
                    231:       meaningful.  <i>Restriction: One word, no hyphens, underscores, or 
                    232:       special characters.</i>
                    233:   </dd>
                    234:   <dt>LON-CAPA host id</dt>
                    235:   <dd>Each LON-CAPA server requires a unique internal name.  We use names
                    236:       such as "msul1" for the first library server. <i>Restriction: One word, 
                    237:       no hyphens, underscores, or special characters.</i>
                    238:   </dd>
                    239:   <dt>Host administrator email</dt>
                    240:   <dd>The amount of email sent to this address is relatively minimal.  Messages
                    241:       are sent every time the system starts up, or if the system is in 
                    242:       serious trouble. On a laptop, make this <tt>root@localhost</tt>.
                    243:   </dd>
                    244: </dl>
                    245: 
                    246: <h2>Configuring LON-CAPA</h2>
                    247: <p>
                    248: To configure and install LON-CAPA, execute the following commands:
                    249: </p>
                    250: <pre>
1.5       matthew   251: cd /root/loncapa-N.N     (N.N should correspond to a version number like '1.2')
1.1       matthew   252: ./UPDATE
                    253: </pre>
                    254: <p>
                    255: You will need to enter the LON-CAPA configuration information you determined 
                    256: in the previous section.  
                    257: </p>
                    258: 
                    259: <h2>Creating a Domain Coordinator</h2>
                    260: <p>
                    261: You will need at least one user at your site who has the role of
                    262: 'domain coordinator'.  This user creates accounts for other users and
                    263: grants them additional privileges.  The make_domain_coordinator.pl script
                    264: invoked below requires that you enter the users password.  The password will
                    265: show in plaintext as you type it.  Feel free to use the "passwd username"
                    266: command to change it later.  Replace USERNAME and DOMAIN with an 
                    267: appropriate user name and your domain.
                    268: </p>
                    269: <pre>
                    270: cd /root/loncapa-N.N/loncom/build
                    271: perl make_domain_coordinator.pl USERNAME DOMAIN
                    272: (WILL PROMPT FOR PASSWORD HERE)
1.8       matthew   273: mkdir ~USERNAME/public_html
                    274: chown USERNAME:www ~USERNAME/public_html
                    275: chmod 0775 ~USERNAME/public_html
                    276: chmod a+x ~USERNAME
1.1       matthew   277: </pre>
                    278: 
                    279: <h2>Start/Restart Services</h2>
                    280: <p>
                    281: The LON-CAPA network services take a moment to start.  Most misconfigurations
                    282: will be appearant at this step.
                    283: </p>
                    284: <pre>
                    285: /etc/init.d/loncontrol start
                    286: /etc/init.d/httpd start
                    287: </pre>
1.5       matthew   288: <p>
                    289: If you receive warnings when starting the httpd about missing perl modules,
                    290: please make sure you followed the instructions in 
                    291: <b>Installing LON-CAPA Dependencies</b>.  If you still have errors, please
                    292: contact the LON-CAPA development team.
                    293: </p>
1.1       matthew   294: <h2>Log in to your LON-CAPA Machine</h2>
                    295: <p>
                    296: Point a web browser at your new machine and log in as the domain
                    297: coordinator.  Congratulations!
                    298: </p>
1.4       matthew   299: 
                    300: <h2>If Things aren't working right</h2>
                    301: <p>
                    302: If you've followed the steps above and the server doesn't start or you think 
                    303: there's something wrong, please get in touch with the LON-CAPA developers.
                    304: If there were errors in installation of the dependency RPMs or during the
                    305: automatic setup, please send us as much information as possible.
                    306: If some part of this document is unclear please let us know.
                    307: </p>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>