Annotation of doc/build/manual_install.frag, revision 1.5

1.1       bowersj2    1: <p>
                      2: You will need to check all the following things to ensure proper
1.2       bowersj2    3: installation of your LON-CAPA system. Be sure to use the <a
                      4: href="rh73.html">RedHat 7.3 specific instructions</a> if they apply,
                      5: as that will be much easier for you.
1.1       bowersj2    6: </p>
                      7: <ul>
1.2       bowersj2    8: <li><a href="#download">Downloading LON-CAPA</a></li>
1.1       bowersj2    9: <li><a href="#wwwuser">
                     10: Creating a user 'www'</a></li>
                     11: <li><a href="#shadow">
                     12: Make a LON-CAPA system work with shadow passwords</a></li>
                     13: <li><a href="#install">
                     14: Installing LON-CAPA files</a></li>
1.5     ! albertel   15: <li><a href="#perl">
        !            16: Installing CPAN modules</a></li>
1.1       bowersj2   17: <li><a href="#checkrpms">
                     18: Checking your Linux RPMs</a> (On RedHat)</li>
                     19: <li><a href="#fixhosts">
                     20: Fixing <tt>/etc/hosts</tt></a></li>
                     21: <li><a href="#mysql">
                     22: Configuring the MySQL database</a></li>
                     23: <li><a href="#testing">
                     24: Testing to see if the LON-CAPA server is operational</a></li>
                     25: </ul>
                     26: 
1.2       bowersj2   27: <a name="download" />
                     28: <h3>Downloading LON-CAPA</h3>
                     29: 
                     30: <p>
                     31: <b>Current Release is Version LATESTVERSION.
                     32: This version was released on LATESTDATE.</b>
                     33: </p>
                     34: <p>
1.4       bowersj2   35: You can download the <b>most current version of LON-CAPA</b> at
1.2       bowersj2   36: <a href="http://install.lon-capa.org/versions/loncapa-current.tar.gz">
1.4       bowersj2   37: http://install.lon-capa.org/versions/loncapa-current.tar.gz</a>
1.2       bowersj2   38: (version LATESTVERSION).
                     39: </p>
                     40: <p>
1.4       bowersj2   41: The <b>development release of LON-CAPA</b> is at:
1.2       bowersj2   42: <a href="http://install.lon-capa.org/versions/loncapa-unstable.tar.gz">
1.4       bowersj2   43: http://install.lon-capa.org/versions/loncapa-unstable.tar.gz</a>.
1.2       bowersj2   44: </p>
                     45: <p>
                     46: To view the code development history of LON-CAPA, you will need to use the
                     47: <a href="http://www.cvshome.org/">CVS</a> tool, the open standard for
                     48: version control.  Please contact Helen (<a href="mailto:helen@lon-capa.org">
                     49: helen@lon-capa.org</a>) to request a CVS USERNAME.
                     50: </p>
                     51: <p>
                     52: The initial CVS commands would be:
                     53: </p>
                     54: <blockquote>
                     55: <table bgcolor="#aaaaaa" border="1">
                     56: <tr><td>
                     57: <pre>
                     58: export CVSROOT=:pserver:USERNAME@zaphod.lite.msu.edu:/home/cvs 
                     59: cvs login 
                     60: cvs co loncapa
                     61: </pre>
                     62: </td></tr></table>
                     63: </blockquote>
                     64: <p>
                     65: For more information on using CVS, please visit
                     66: <a href="http://www.cvshome.org/">http://www.cvshome.org/</a>
                     67: or read <tt>loncom/build/readme.html</tt> after downloading
                     68: the current version of LON-CAPA as described above.
                     69: </p>
                     70: 
1.1       bowersj2   71: <a name="wwwuser" />
                     72: <h3>Creating a user 'www'</h3>
                     73: <p>
                     74: Execute the following command to create a user named 'www' on your
                     75: LON-CAPA server:
                     76: </p>
                     77: <table bgcolor="#aaaaaa" border="1"><tr><td>
                     78: <tt>/usr/sbin/useradd www</tt>
                     79: </td></tr></table>
                     80: <a name="shadow" />
                     81: <h3>Make a LON-CAPA system work with shadow passwords</h3>
                     82: <table border="1">
                     83: <tr><th>Step #</th><th>Description</th></tr>
                     84: <tr><td>
                     85: <font size="+1">1</font>
                     86: </td><td>
                     87: <p>Is your system using shadow passwords? (Note: LON-CAPA will work
                     88: with either MD5/non-MD5 configured systems).  It is strongly
                     89: recommended to use shadow passwords. If your system is currently not
                     90: using shadow passwords, run the "pwconv" command (as root) in order to
                     91: convert to shadow passwords.  If you choose not to use shadow
                     92: passwords, then do not perform any of the additional steps.  If your
                     93: system is using shadow passwords, then you will need to perform the
                     94: additional steps below. 
                     95: </p>
                     96: <p>
                     97: <strong>How to detect:</strong>
                     98: <br />command: <tt>cat /etc/passwd | grep ':x:'</tt>
                     99: </p>
                    100: <p>If there is output such as "<tt>root:x:0:0:root:/root:/bin/bash</tt>",
                    101: then your system is using shadow passwords and you will need to continue with
                    102: the steps below.
                    103: </p>
                    104: </td></tr>
                    105: <tr><td>
                    106: <font size='+1'>2</font>
                    107: </td><td>
                    108: <p><strong>Retrieve the mod_auth_external source</strong> by
                    109: running the following command
                    110: </p>
                    111: <p><tt>
                    112: wget http://www.unixpapa.com/software/mod_auth_external-2.1.15.tar.gz
                    113: </tt>
                    114: </p>
                    115: </td></tr>
                    116: <tr><td>
                    117: <font size='+1'>3</font>
                    118: </td><td>
                    119: <p><strong>Unpack the mod_auth_external source</strong> by
                    120: running the following command
                    121: </p>
                    122: <p>
                    123: <tt>tar xzvf mod_auth_external-2.1.15.tar.gz</tt>
                    124: </p>
                    125: </td></tr>
                    126: <tr><td>
                    127: <font size='+1'>4</font>
                    128: </td><td>
                    129: <p><strong>Go to the <tt>pwauth</tt> directory</strong> by
                    130: running the following command
                    131: </p>
                    132: <p>
                    133: <tt>cd mod_auth_external-2.1.15/pwauth/</tt>
                    134: </p>
                    135: </td></tr>
                    136: <tr><td>
                    137: <font size='+1'>5</font>
                    138: </td><td>
                    139: <p><strong>Edit <tt>config.h</tt> and change SERVER_UIDS definition</strong>
                    140: </p>
                    141: <p>
                    142: Determine the user id of 'www':
                    143: <br /><tt>id -u www</tt>
                    144: <br />
                    145: Change the line
                    146: <br /><tt>#define SERVER_UIDS 99       /* user "nobody" */</tt>
                    147: <br />to be
                    148: <br /><tt>#define SERVER_UIDS 513      /* user "www" */</tt>
                    149: <br />where in this example 513 corresponds to the user id of 'www'.
                    150: </p>
                    151: </td></tr>
                    152: <tr><td>
                    153: <font size='+1'>6</font>
                    154: </td><td>
                    155: <p><strong>Compile the <tt>pwauth</tt> executable</strong> by
                    156: running the following command
                    157: </p>
                    158: <p>
                    159: <tt>make</tt>
                    160: </p>
                    161: </td></tr>
                    162: <tr><td>
                    163: <font size='+1'>7</font>
                    164: </td><td>
                    165: <p><strong>Install <tt>pwauth</tt></strong> by doing the following
                    166: </p>
                    167: <p>
                    168: <tt>cp pwauth /usr/local/sbin/</tt>
                    169: <br /><tt>chmod 6755 /usr/local/sbin/pwauth</tt>
                    170: </p>
                    171: <p>
                    172: Edit (creating the file) /etc/pam.d/pwauth to have the contents:
                    173: </p>
                    174: <pre>
                    175:         auth       required     /lib/security/pam_pwdb.so shadow nullok
                    176:         auth       required     /lib/security/pam_nologin.so
                    177:         account    required     /lib/security/pam_pwdb.so
                    178: </pre>
                    179: </td></tr>
                    180: </table>
                    181: <a name="install" />
                    182: <h3>Installing LON-CAPA files</h3>
                    183: <p>
                    184: Download the most current
                    185: <a href="http://install.lon-capa.org/versions/loncapa-current.tar.gz">
                    186: loncapa-current.tar.gz</a>.
                    187: </p>
                    188: <table bgcolor="#aaaaaa" border="1">
                    189: <tr><td><tt>wget http://install.lon-capa.org/versions/loncapa-current.tar.gz
                    190: </tt>
                    191: <br />
                    192: <tt>tar xzvf loncapa-current.tar.gz</tt>
                    193: <br />
                    194: <tt>cd loncapa-N.N</tt> (N.N is the version number)</td></tr>
                    195: </table>
                    196: <p>
                    197: The <strong>UPDATE</strong> command will refresh your filesystem with all
                    198: the latest LON-CAPA software.
                    199: </p>
                    200: <table bgcolor="#aaaaaa" border="1">
                    201: <tr><td><tt>./UPDATE</tt></td></tr>
                    202: </table>
1.5     ! albertel  203: <a name="perl" />
        !           204: <h3>Installing CPAN modules</h3>
        !           205: 
        !           206: <p> Lon-CAPA uses a large numbe of perl modules that need to be
        !           207: installed. Some of these may be available on your machine already,
        !           208: some can be gotten from packages in your Linux Distribution. Some will probably need to come from CPAN </p>
        !           209: 
        !           210: <p> You can check which modules you have and which ones you need by
        !           211: running the TEST script. It will generate a CPAN_STATUS_REPORT.
        !           212: You can install an missing perl modules by doing:
        !           213: <table bgcolor="#aaaaaa" border="1">
        !           214: <tr><td><tt>perl -MCPAN -e 'install MODULENAME'</tt></td></tr>
        !           215: </table>
        !           216: Where MODULENAME is the perl module you need to install.
        !           217: </p>
        !           218: <p>
        !           219: 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>
        !           220:  </p>
        !           221: 
1.1       bowersj2  222: <a name="checkrpms" />
                    223: <h3>Checking your Linux RPMs on RedHat</h3>
                    224: <p>
                    225: The <strong>CHECKRPMS</strong> command will check the RPMs on your machine
                    226: against an FTP repository, if you're using a RedHat server.
                    227: </p>
                    228: 
                    229: <table bgcolor="#aaaaaa" border="1">
                    230: <tr><td><tt>./CHECKRPMS</tt></td></tr>
                    231: </table>
                    232: 
                    233: <p>If you are not installing on RedHat, you may need to manually
                    234: install some software. The following pointers may be useful:</p>
                    235: 
1.2       bowersj2  236: <ul><li>LON-CAPA uses a lot of Perl modules. If you are using RedHat,
                    237: go to <a href="http://install.lon-capa.org/resources">this
                    238: directory</a> and download the latest
                    239: <b>LON-CAPA-systemperl-?.?-rh7.i386.rpm</b>, which will contain all
                    240: the Perl modules you need on RedHat. Use <tt>rpm-Uvh --force</tt> to
                    241: install the RPM; this will overwrite some currently existing files and
                    242: that's OK.
                    243: 
                    244: <br /><br />For other Linux distributions, the easiest way to figure
1.1       bowersj2  245: out what Perl modules are being used by LON-CAPA that you do not have
                    246: installed is to try to start up LON-CAPA and see what Perl complains
                    247: about missing. Start by trying to run <tt>/home/httpd/perl/lonc</tt>
                    248: and <tt>/home/httpd/perl/lond</tt> manually as the <tt>www</tt> user,
                    249: and install the modules it complains about not finding. How you
                    250: install those modules will be distribution-specific, but failing all
                    251: else, you can use CPAN; see <tt>man CPAN</tt> on your distribution.<br
                    252: /><br />Once you've gotten <tt>lonc</tt> and <tt>lond</tt> to run, try
                    253: starting up the webserver. How long this will take depends entirely on
                    254: how close your distribution came to having all the modules LON-CAPA
                    255: uses when you started.</li>
                    256: <li>LON-CAPA assumes that the apache web server will be named "httpd"
                    257: and have configuration directories in <tt>/etc/httpd</tt>. Some distributions 
                    258: have that directory at <tt>/etc/apache</tt>. Symlinking <tt>httpd</tt> to the correct 
                    259: directory should work.</li>
                    260: </ul>
                    261: <a name="fixhosts" />
                    262: <h3>Fixing <tt>/etc/hosts</tt></h3>
                    263: <p>
                    264: A common RedHat glitch of new installations (RedHat's fault, not LON-CAPA)
                    265: is the generation of /etc/hosts.
                    266: </p>
                    267: <p>
                    268: It should look something like this (except the <tt>myschool</tt> line
                    269: should be replaced with settings specific to your machine):
                    270: </p>
                    271: <table bgcolor="#aaaaaa" border="1">
                    272: <tr><td>
                    273: <pre>
                    274: 127.0.0.1		localhost.localdomain localhost
                    275: 12.34.56.78		www.myschool.edu myschool
                    276: </pre></td></tr>
                    277: </table>
                    278: <a name="mysql" />
                    279: <h3>Configuring the MySQL database</h3>
                    280: <p>
                    281: The following commands describe how to configure the MySQL database
                    282: on your LON-CAPA server.
                    283: <br />Note:
                    284: </p>
                    285: <ul>
                    286: <li>you should substitute 'ROOTPASSWORD' with something very hard to guess
                    287: (it does not have to be the Linux OS root password)
                    288: </li>
                    289: <li>The MySQL www@localhost user must always have a password of 'localhostkey'
                    290: in order for there to be correct operation of a standard LON-CAPA system.
                    291: </li>
                    292: </ul>
                    293: <p>
                    294: The following instructions assume you are logged in as 'root'.
                    295: </p>
                    296: <p>Entering the mysql shell</p>
                    297: <table bgcolor="#aaaaaa" border="1"><tr><td>
                    298: <pre>
                    299: mysql -u root -p mysql
                    300: OR
                    301: mysql -u root mysql (depending on whether you have set a root password)
                    302: </pre>
                    303: </td></tr></table>
                    304: <p>Creating the mysql 'www' user (after entering mysql shell)</p>
                    305: <table bgcolor="#aaaaaa" border="1"><tr><td>
                    306: <pre>
                    307: mysql> CREATE DATABASE loncapa;
                    308: 
                    309: mysql> INSERT INTO user (Host, User, Password)
                    310: mysql> VALUES ('localhost','www',password('localhostkey'));
                    311: 
                    312: mysql> INSERT INTO db VALUES ('localhost','loncapa','www',
                    313: mysql> 'Y','Y','Y','Y','Y','Y','N','Y','Y','Y');
                    314: 
                    315: mysql> FLUSH PRIVILEGES;
                    316: </pre>
                    317: </td></tr></table>
                    318: <p>SECURITY: set a password for the mysql 'root' user</p>
                    319: <table bgcolor="#aaaaaa" border="1"><tr><td>
                    320: <pre>
                    321: shell> mysql -u root mysql
                    322: mysql> SET PASSWORD FOR root@localhost=PASSWORD('ROOTPASSWORD');
                    323: </pre>
                    324: </td></tr></table>
                    325: <p>SECURITY: only allow access from localhost</p>
                    326: <table bgcolor="#aaaaaa" border="1"><tr><td>
                    327: <pre>
                    328: shell> mysql -u root -p mysql
                    329: mysql> DELETE FROM user WHERE host&lt;&gt;'localhost';
                    330: </pre>
                    331: </td></tr></table>
                    332: <a name="testing" />
                    333: <h3>Testing to see if the LON-CAPA server is operational</h3>
                    334: <p>
                    335: The <strong>TEST</strong> command will check the installation software,
                    336: the perl libraries on your system, the MySQL database, and
                    337: will also automatically test the real-time operation of the 
                    338: LON-CAPA Apache web server.
                    339: </p>
                    340: <table bgcolor="#aaaaaa" border="1">
                    341: <tr><td><tt>./TEST</tt></td></tr>
                    342: </table>
                    343: <p>
                    344: Using the <strong>TEST</strong> command will likely
                    345: be an iterative process.
                    346: It is normal to expect that the <strong>TEST</strong> command
                    347: will recommend you perform various steps to ensure optimal
                    348: performance of your LON-CAPA server.
                    349: </p>
                    350: <!-- maintext end -->
                    351: <!-- validated -->
                    352: </body>
                    353: </html>

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