View of /trunk/webwork/webworkdocs/installation/readme.install

    1 readme.install file for WeBWorK version 1.8
    2 
    3 **********************************************************************
    4 
    5 The basic requirements for setting up WeBWorK is a unix system running the
    6 apache webserver, perl, and LaTeX. Probably your system already has all these
    7 installed. In addition for the readable display of mathematical expressions you
    8 will need tth, latex2html, and dvipng. You can make do with a subset of these,
    9 but we recommend you install all of them.  You will need a system administrator
   10 to do some of the set up and it would be a good idea for him or her to be
   11 involved from the beginning.  Our system admin is Hoss Firooznia
   12 (hfir@math.rochester.edu) and he would certainly be willing to answer questions.
   13 Similarly,  Mike Gage (gage@math.rochester.edu) or Arnie Pizer
   14 (apizer@math.rochester.edu) are willing to help.
   15 
   16 
   17 1. Download the following files using a web browser (ftp access is not allowed).
   18 Connect to http://webhost.math.rochester.edu/webworkdocs/ and then click on
   19 Download Software and follow the instructions. You will have to register to
   20 download files. If you have difficulty registering, contact Gage or Pizer.
   21 
   22 webwork_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz
   23 templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz
   24 
   25 and also:
   26 
   27 readme.first
   28 readme.install
   29 readme.upgrade
   30 overview.html
   31 linux.html (really instructions for setting up WeBWorK on any unix system)
   32 linux-redhat-8.0.html (instructions for setting up RedHat 8.0 as a WeBWorK server)
   33 
   34 These six files are contained in webwork_X.X_XX-MONTH-XX-XXXX.tar.gz but you
   35 should look at
   36 overview.html and
   37 readme.install
   38 for information on where to install the files.  Even if you are not using
   39 RedHat, we recommend that you read linux-redhat-8.0.html as this contains
   40 useful information.
   41 
   42 
   43 3. Unzip and untar the tar file webwork_1.8_XXX.tar.gz tar -xzvf
   44 webwork_1.8_XXX.tar.gz This will create the directory webwork_1.8_XXX containing
   45 the main webwork directory and six additional files: three readme files
   46 (readme.first, readme.install, readme.upgrade), an overview of the setup
   47 procedure (overview.html),the detailed setup procedure (linux.html), and a
   48 detailed explaination for setting up a server for WeBWorK using RedHat Linux 8.0
   49 (linux-redhat-8.0.html).  Follow the procedures in these documents.
   50 
   51 After you set up the demoCourse, when you connect to demoCourse, you will see a
   52 link to the WeBWorK documentation. We have a lot of documentation (most of which
   53 we hope is correct).   It's not that well organized so you have to hunt around
   54 for stuff. The documentation we use the most is "A DAY IN THE LIFE OF A WEBWORK
   55 PROFESSOR"
   56 
   57 http://webwork.math.rochester.edu/docs/docs/courseadmin/usingwebwork.html
   58 
   59 Also  see the doc's on using the pg language (for writing problems)
   60 
   61 http://webwork.math.rochester.edu/docs/docs/pglanguage/
   62 
   63 This is a discussion group where you can ask questions and hopefully receive
   64 answers from other WeBWorK users (and or search through questions, answers,
   65 and documentation).
   66 
   67 http://webhost.math.rochester.edu/webworkdocs/discuss/
   68 
   69 4. We use the pg language (almost perl with some macros) for writing problems.
   70 The templates_X.X_XX-MONTH-XX-XXXX.tar.gz file contains a library approximately
   71 2500 WeBWorK problems covering pre-calculus, first year calculus, vector
   72 calculus, differential equations, probability, and statistics.  These are all
   73 written in the pg language and should serve as good examples in case you want to
   74 write your own problems. In addition you can connect to
   75 http://webwork-db.math.rochester.edu/cgi-bin/cvsweb.cgi/ and download problems
   76 written at other institutions.
   77 
   78 5. You shouldn't really change the demoCourse (unless you are sure you know what
   79 you are doing).  IMPORTANT NOTE , the (binary) databases are sytem dependent so
   80 we have not included the ones for the demoCourse in this distribution. You will
   81 have follow the instructions on initializing passwords, setting prof privileges,
   82 and building problem sets. After you have the demoCourse working, set up a new
   83 course and then play with it to your hearts content.  Your demoCourse should be
   84 similar to ours: http://webwork.math.rochester.edu/courses/demoCourse . Note:
   85 the latex2html gifs for the demoCourse have not been pre created.  Thus if you
   86 select "typeset" mode there will be a delay as the gifs are created on the fly
   87 (assuming everything works). Depending on your system, the actual TeX fonts may
   88 be created on the fly the first few times if TeX is new on your system. If you
   89 view the problem again, there will be no delay as the gifs are stored and reused
   90 (unless you have edited the problem template in the mean time). "typeset2" mode,
   91 which uses dvipng, is much faster than latex2html and provides the same quality
   92 images. Also you will have to install tth binary (which is needed for "formatted
   93 text" mode). Install the correct binary for your system.  Directions for doing
   94 this are given in linux.html.  Initially, we suggest you test things out using
   95 "text" mode.
   96 
   97 6. By default, WeBWorK used the gdbm database. You can also use the Berkeley
   98 db database by changing a setting in Global.pm (or in an individual course).
   99 Be warned that we have not tested things extensively with the db database. We
  100 highly reccommend you use gdbm.
  101 
  102 7. Here is the general structure: webwork/courses contains individual courses
  103 and webwork/system contains all the common system files. The file
  104 .../system/lib/Global.pm contains defaults for the whole system. Most of these
  105 can be over ridden for a particular course in the e.g.
  106 .../courses/mth140a/webworkCourse.ph file.   This file is created when you set
  107 up a new course (mth140a in the above example).  As an example, $htmlModeDefault
  108 = 'Latex2HTML';   in webworkCourse.ph overrides $htmlModeDefault = 'HTML';   in
  109 Global.pm for the mth140a course.  In general, the webworkCourse.ph file
  110 contains course specific information. E.g. if a prof doesn't want to use
  111 latex2html, copying
  112 
  113   # The rendering modes for onscreen problem display which are available to the student.
  114   # Modes can be added, or commented out here. Adding a new mode required additional changes.
  115   # The format is [internal symbol, external name].
  116   $available_mode_list = [
  117           ['HTML', 'text'],
  118           ['HTML_tth', 'formatted-text'],
  119           ['HTML_dpng' ,'typeset2'],
  120           ['Latex2HTML', 'typeset']
  121   ];
  122 
  123 from Global.pm to webworkCourse.ph and then commenting out the
  124 "['Latex2HTML', 'typeset']" line will eliminate all references to "typeset" mode
  125 for his or her course. Or a prof could change the external name for a mode.
  126 
  127 8. Different courses can use different macros for writing and answering
  128 problems.  By default, all courses use the same macros found in
  129 .../system/courseScripts. One can change this in webworkCourse.ph to point to
  130 course specific macros.  Look at these files especially if you want to write
  131 your own answering mechanisms and/or problem writing macros.  Our hope is that
  132 this will become a little like TeX.  Standard macros used by almost everybody
  133 that can be added to by individuals.  The point is that one can change quite a
  134 few things without changing the system code.  In practice, most users will be
  135 content to use the standard macros in .../system/courseScripts.
  136 
  137 9. If you do try to improve the code, please inform us of any suggested changes.
  138 We certainly want to maintain one consistent WeBWorK product.  The is one reason
  139 for us copyrighting the "WeBWorK" name.
  140 
  141 10.  Trouble shooting.  The thing that causes the most problems is permissions.
  142 If you carefully follow the set up procedures, we hope you won't have problems.
  143 Also sometimes the paths to required unix programs are wrong.  Again if you
  144 carefully follow the set up procedures, this should not occur. If it does, look
  145 at the messages in WeBWorK's error log (see below).
  146 
  147 Further look in the error logs for your webserver and in WeBWorK's error log
  148 .../webwork/system/logs/error_log.
  149 
  150 For debugging errors in output (postscript,latex2html, etc), set $imageDebugMode
  151 to 1 in Global.pm and then look at the messages in WeBWorK's error log
  152 ( .../webwork/system.logs/error_log) and in the webserver's error log.
  153 Also with $imageDebugMode set to 1 intermediate temporary files (log files,
  154 TeX files, etc) will be saved and these may help in finding the error.
  155 You will find these files in the course's tmp directory. Don't leave
  156 $imageDebugMode set to 1. If you do, you will find your file system filling up.
  157 
  158 If you have difficulty displaying graphs look at the system dependent scripts
  159 gif2eps and png2eps in the .../webwork/system/scripts directory.  Remove the
  160 -nosetpage switch which is required for some versions of pnmtops and invalid
  161 for other versions.
  162 
  163 If you do still have trouble (especially if you see Internal Server Error),
  164 edit .../webwork/system/lib/webworkConfig.pm setting
  165 $cgiDebugMode = 1;
  166 $cgiDebugMode, when enabled, will call the debug wrapper scripts instead of the
  167 cgi scripts themselves, allowing for header output, etc. In addition to setting
  168 $cgiDebugMode =1, you will also need to enable debugging in the wrapper script
  169 for the cgi script that you wish to debug, by setting $debug = 1. Wrapper
  170 scripts are found in the directory referred to by $cgiWebworkURL, which is
  171 usually webwork/system/cgi and have the same name as the underlying cgi script.
  172 
  173 11. Some problems have a hard coded statement that you have to get all parts
  174 correct in order to receive credit.  This is not true if the partial credit
  175 problem grader is used.  In general, it is better to let the software generate
  176 such statements rather than put them in problems.  But we have not edited them
  177 all out.  Also some problems have the statement that you have to use a * to
  178 denote multiplication. This is no longer true. A few problems have references to
  179 specific texts.  They may have to be edited.
  180 
  181 12. Initially we ran WeBWorK under IRIX on an SGI Indy.  We then ran it under
  182 FreeBSD on a pentium II 400 mhz machine with about 900 students (in several
  183 classes, the largest having about 250 students). We started running into
  184 performance problems so we switched to a dual procesor pentium III 500 mhz
  185 server from Dell (cost $2,300) still using FreeBSD. That machine provided good
  186 performance.  We just switched to a Dell PowerEdge 4600 with dual 2 GHz Xeon
  187 processors (cost $5,000).  This is one fast machine wich is more than adequate
  188 for the 1300 students we have using the system.  Others have installed WeBWorK
  189 on PC's running Red Hat Linux, Solaris, and on alpha workstations. There are
  190 well know performance problems associated with running very busy interactive web
  191 sites (and WeBWorK is highly interactive). We expect with the present software,
  192 WeBWorK will have performance problems with very large classes or on old, slow
  193 hardware.  We hope to address these potential problems with a mod_perl
  194 release of WeBWorK in the future.
  195 
  196 13. It would be very helpful to us if you could keep track of how the
  197 installation process goes and tell us about confusing instructions,
  198 errors, suggestions for improvements, etc.
  199 
  200 Mike Gage and Arnie Pizer