File:  [LON-CAPA] / doc / build / manual_install.frag
Revision 1.8: download - view: text, annotated - select for diffs
Wed Oct 22 21:32:00 2008 UTC (13 years, 7 months ago) by raeburn
Branches: MAIN
CVS tags: version_2_9_X, version_2_9_99_0, version_2_9_1, version_2_9_0, version_2_8_X, version_2_8_99_1, version_2_8_99_0, version_2_8_2, version_2_8_1, version_2_8_0, version_2_7_99_1, version_2_7_99_0, version_2_12_X, version_2_11_X, version_2_11_4_uiuc, version_2_11_4_msu, version_2_11_4, version_2_11_3_uiuc, version_2_11_3_msu, version_2_11_3, version_2_11_2_uiuc, version_2_11_2_msu, version_2_11_2_educog, version_2_11_2, version_2_11_1, version_2_11_0_RC3, version_2_11_0_RC2, version_2_11_0_RC1, version_2_11_0, version_2_10_X, version_2_10_1, version_2_10_0_RC2, version_2_10_0_RC1, version_2_10_0, loncapaMITrelate_1, language_hyphenation_merge, language_hyphenation, bz6209-base, bz6209, HEAD, GCI_3, GCI_2, GCI_1, BZ4492-merge, BZ4492-feature_horizontal_radioresponse, BZ4492-feature_Support_horizontal_radioresponse, BZ4492-Support_horizontal_radioresponse
Update CVS location and Contact information.

<p>
You will need to check all the following things to ensure proper
installation of your LON-CAPA system. Be sure to use the <a
href="rh73.html">RedHat 7.3</a> or <a href="fedora_install.html">Fedora</a> specific instructions if they apply,
as that will be much easier for you.
</p>
<ul>
<li><a href="#download">Downloading LON-CAPA</a></li>
<li><a href="#wwwuser">
Creating a user 'www'</a></li>
<li><a href="#shadow">
Make a LON-CAPA system work with shadow passwords</a></li>
<li><a href="#install">
Installing LON-CAPA files</a></li>
<li><a href="#perl">
Installing CPAN modules</a></li>
<li><a href="#checkrpms">
Checking your Linux RPMs</a> (On RedHat)</li>
<li><a href="#fixhosts">
Fixing <tt>/etc/hosts</tt></a></li>
<li><a href="#mysql">
Configuring the MySQL database</a></li>
<li><a href="#testing">
Testing to see if the LON-CAPA server is operational</a></li>
</ul>

<a name="download" />
<h3>Downloading LON-CAPA</h3>

<p>
<b>Current Release is Version LATESTVERSION.
This version was released on LATESTDATE.</b>
</p>
<p>
You can download the <b>most current version of LON-CAPA</b> at
<a href="http://install.lon-capa.org/versions/loncapa-current.tar.gz">
http://install.lon-capa.org/versions/loncapa-current.tar.gz</a>
(version LATESTVERSION).
</p>
<p>
The <b>development release of LON-CAPA</b> is at:
<a href="http://install.lon-capa.org/versions/loncapa-unstable.tar.gz">
http://install.lon-capa.org/versions/loncapa-unstable.tar.gz</a>.
</p>
<p>
To view the code development history of LON-CAPA, you will need to use the
<a href="http://www.cvshome.org/">CVS</a> tool, the open standard for
version control.  Please contact the MSU LON-CAPA group 
(<a href="mailto:helpdesk@lon-capa.org">helpdesk@lon-capa.org</a>) to request a 
CVS USERNAME.
</p>
<p>
The initial CVS commands would be:
</p>
<blockquote>
<table bgcolor="#aaaaaa" border="1">
<tr><td>
<pre>
export CVSROOT=:ext:USERNAME@source.lon-capa.org:/home/cvs 
cvs login 
cvs co loncapa
</pre>
</td></tr></table>
</blockquote>
<p>
For more information on using CVS, please visit
<a href="http://www.cvshome.org/">http://www.cvshome.org/</a>
or read <tt>loncom/build/readme.html</tt> after downloading
the current version of LON-CAPA as described above.
</p>

<a name="wwwuser" />
<h3>Creating a user 'www'</h3>
<p>
Execute the following command to create a user named 'www' on your
LON-CAPA server:
</p>
<table bgcolor="#aaaaaa" border="1"><tr><td>
<tt>/usr/sbin/useradd www</tt>
</td></tr></table>
<a name="shadow" />
<h3>Make a LON-CAPA system work with shadow passwords</h3>
<table border="1">
<tr><th>Step #</th><th>Description</th></tr>
<tr><td>
<font size="+1">1</font>
</td><td>
<p>Is your system using shadow passwords? (Note: LON-CAPA will work
with either MD5/non-MD5 configured systems).  It is strongly
recommended to use shadow passwords. If your system is currently not
using shadow passwords, run the "pwconv" command (as root) in order to
convert to shadow passwords.  If you choose not to use shadow
passwords, then do not perform any of the additional steps.  If your
system is using shadow passwords, then you will need to perform the
additional steps below. 
</p>
<p>
<strong>How to detect:</strong>
<br />command: <tt>cat /etc/passwd | grep ':x:'</tt>
</p>
<p>If there is output such as "<tt>root:x:0:0:root:/root:/bin/bash</tt>",
then your system is using shadow passwords and you will need to continue with
the steps below.
</p>
</td></tr>
<tr><td>
<font size='+1'>2</font>
</td><td>
<p><strong>Retrieve the mod_auth_external source</strong> by
running the following command
</p>
<p><tt>
wget http://www.unixpapa.com/software/mod_auth_external-2.1.15.tar.gz
</tt>
</p>
</td></tr>
<tr><td>
<font size='+1'>3</font>
</td><td>
<p><strong>Unpack the mod_auth_external source</strong> by
running the following command
</p>
<p>
<tt>tar xzvf mod_auth_external-2.1.15.tar.gz</tt>
</p>
</td></tr>
<tr><td>
<font size='+1'>4</font>
</td><td>
<p><strong>Go to the <tt>pwauth</tt> directory</strong> by
running the following command
</p>
<p>
<tt>cd mod_auth_external-2.1.15/pwauth/</tt>
</p>
</td></tr>
<tr><td>
<font size='+1'>5</font>
</td><td>
<p><strong>Edit <tt>config.h</tt> and change SERVER_UIDS definition</strong>
</p>
<p>
Determine the user id of 'www':
<br /><tt>id -u www</tt>
<br />
Change the line
<br /><tt>#define SERVER_UIDS 99       /* user "nobody" */</tt>
<br />to be
<br /><tt>#define SERVER_UIDS 513      /* user "www" */</tt>
<br />where in this example 513 corresponds to the user id of 'www'.
</p>
</td></tr>
<tr><td>
<font size='+1'>6</font>
</td><td>
<p><strong>Compile the <tt>pwauth</tt> executable</strong> by
running the following command
</p>
<p>
<tt>make</tt>
</p>
</td></tr>
<tr><td>
<font size='+1'>7</font>
</td><td>
<p><strong>Install <tt>pwauth</tt></strong> by doing the following
</p>
<p>
<tt>cp pwauth /usr/local/sbin/</tt>
<br /><tt>chmod 6755 /usr/local/sbin/pwauth</tt>
</p>
<p>
Edit (creating the file) /etc/pam.d/pwauth to have the contents:
</p>
<pre>
        auth       required     /lib/security/pam_pwdb.so shadow nullok
        auth       required     /lib/security/pam_nologin.so
        account    required     /lib/security/pam_pwdb.so
</pre>
</td></tr>
</table>
<a name="install" />
<h3>Installing LON-CAPA files</h3>
<p>
Download the most current
<a href="http://install.lon-capa.org/versions/loncapa-current.tar.gz">
loncapa-current.tar.gz</a>.
</p>
<table bgcolor="#aaaaaa" border="1">
<tr><td><tt>wget http://install.lon-capa.org/versions/loncapa-current.tar.gz
</tt>
<br />
<tt>tar xzvf loncapa-current.tar.gz</tt>
<br />
<tt>cd loncapa-N.N</tt> (N.N is the version number)</td></tr>
</table>
<p>
The <strong>UPDATE</strong> command will refresh your filesystem with all
the latest LON-CAPA software.
</p>
<table bgcolor="#aaaaaa" border="1">
<tr><td><tt>./UPDATE</tt></td></tr>
</table>
<a name="perl" />
<h3>Installing CPAN modules</h3>

<p> Lon-CAPA uses a large numbe of perl modules that need to be
installed. Some of these may be available on your machine already,
some can be gotten from packages in your Linux Distribution. Some will probably need to come from CPAN </p>

<p> You can check which modules you have and which ones you need by
running the TEST script. It will generate a CPAN_STATUS_REPORT.
You can install an missing perl modules by doing:
<table bgcolor="#aaaaaa" border="1">
<tr><td><tt>perl -MCPAN -e 'install MODULENAME'</tt></td></tr>
</table>
Where MODULENAME is the perl module you need to install.
</p>
<p>
More documentation on how CPAN works is available <a href="http://www.perl.com/CPAN/misc/cpan-faq.html#How_install_Perl_modules">here</a>
 </p>

<a name="checkrpms" />
<h3>Checking your Linux RPMs on RedHat</h3>
<p>
The <strong>CHECKRPMS</strong> command will check the RPMs on your machine
against an FTP repository, if you're using a RedHat server.
</p>

<table bgcolor="#aaaaaa" border="1">
<tr><td><tt>./CHECKRPMS</tt></td></tr>
</table>

<p>If you are not installing on RedHat, you may need to manually
install some software. The following pointers may be useful:</p>

<ul><li>LON-CAPA uses a lot of Perl modules. If you are using RedHat,
go to <a href="http://install.lon-capa.org/resources">this
directory</a> and download the latest
<b>LON-CAPA-systemperl-?.?-rh7.i386.rpm</b>, which will contain all
the Perl modules you need on RedHat. Use <tt>rpm-Uvh --force</tt> to
install the RPM; this will overwrite some currently existing files and
that's OK.

<br /><br />For other Linux distributions, the easiest way to figure
out what Perl modules are being used by LON-CAPA that you do not have
installed is to try to start up LON-CAPA and see what Perl complains
about missing. Start by trying to run <tt>/home/httpd/perl/lonc</tt>
and <tt>/home/httpd/perl/lond</tt> manually as the <tt>www</tt> user,
and install the modules it complains about not finding. How you
install those modules will be distribution-specific, but failing all
else, you can use CPAN; see <tt>man CPAN</tt> on your distribution.<br
/><br />Once you've gotten <tt>lonc</tt> and <tt>lond</tt> to run, try
starting up the webserver. How long this will take depends entirely on
how close your distribution came to having all the modules LON-CAPA
uses when you started.</li>
<li>LON-CAPA assumes that the apache web server will be named "httpd"
and have configuration directories in <tt>/etc/httpd</tt>. Some distributions 
have that directory at <tt>/etc/apache</tt>. Symlinking <tt>httpd</tt> to the correct 
directory should work.</li>
</ul>
<a name="fixhosts" />
<h3>Fixing <tt>/etc/hosts</tt></h3>
<p>
A common RedHat glitch of new installations (RedHat's fault, not LON-CAPA)
is the generation of /etc/hosts.
</p>
<p>
It should look something like this (except the <tt>myschool</tt> line
should be replaced with settings specific to your machine):
</p>
<table bgcolor="#aaaaaa" border="1">
<tr><td>
<pre>
127.0.0.1		localhost.localdomain localhost
12.34.56.78		www.myschool.edu myschool
</pre></td></tr>
</table>
<a name="mysql" />
<h3>Configuring the MySQL database</h3>
<p>
The following commands describe how to configure the MySQL database
on your LON-CAPA server.
<br />Note:
</p>
<ul>
<li>you should substitute 'ROOTPASSWORD' with something very hard to guess
(it does not have to be the Linux OS root password)
</li>
<li>The MySQL www@localhost user must always have a password of 'localhostkey'
in order for there to be correct operation of a standard LON-CAPA system.
</li>
</ul>
<p>
The following instructions assume you are logged in as 'root'.
</p>
<p>Entering the mysql shell</p>
<table bgcolor="#aaaaaa" border="1"><tr><td>
<pre>
mysql -u root -p mysql
OR
mysql -u root mysql (depending on whether you have set a root password)
</pre>
</td></tr></table>
<p>Creating the mysql 'www' user (after entering mysql shell)</p>
<table bgcolor="#aaaaaa" border="1"><tr><td>
<pre>
mysql> CREATE DATABASE loncapa;

mysql> INSERT INTO user (Host, User, Password)
mysql> VALUES ('localhost','www',password('localhostkey'));

mysql> INSERT INTO db VALUES ('localhost','loncapa','www',
mysql> 'Y','Y','Y','Y','Y','Y','N','Y','Y','Y');

mysql> FLUSH PRIVILEGES;
</pre>
</td></tr></table>
<p>SECURITY: set a password for the mysql 'root' user</p>
<table bgcolor="#aaaaaa" border="1"><tr><td>
<pre>
shell> mysql -u root mysql
mysql> SET PASSWORD FOR root@localhost=PASSWORD('ROOTPASSWORD');
</pre>
</td></tr></table>
<p>SECURITY: only allow access from localhost</p>
<table bgcolor="#aaaaaa" border="1"><tr><td>
<pre>
shell> mysql -u root -p mysql
mysql> DELETE FROM user WHERE host&lt;&gt;'localhost';
</pre>
</td></tr></table>
<a name="testing" />
<h3>Testing to see if the LON-CAPA server is operational</h3>
<p>
The <strong>TEST</strong> command will check the installation software,
the perl libraries on your system, the MySQL database, and
will also automatically test the real-time operation of the 
LON-CAPA Apache web server.
</p>
<table bgcolor="#aaaaaa" border="1">
<tr><td><tt>./TEST</tt></td></tr>
</table>
<p>
Using the <strong>TEST</strong> command will likely
be an iterative process.
It is normal to expect that the <strong>TEST</strong> command
will recommend you perform various steps to ensure optimal
performance of your LON-CAPA server.
</p>
<!-- maintext end -->
<!-- validated -->
</body>
</html>

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