** Using WeBWorK **

The basic requirements for setting up WeBWorK is a unix system running the apache webserver, perl, and LaTeX. Probably your system already has all these installed. In addition for the readable display of mathematical expressions you will need tth, latex2html, and dvipng. You can make do with a subset of these, but we recommend you install all of them. You will need a system administrator to do some of the set up and it would be a good idea for him or her to be involved from the beginning. Our system admin is Hoss Firooznia (hfir@math.rochester.edu) and he would certainly be willing to answer questions. Similarly, Mike Gage (gage@math.rochester.edu) or Arnie Pizer (apizer@math.rochester.edu) are willing to help.

1. Download the following files using a web browser (ftp access is not allowed). Connect to http://webhost.math.rochester.edu/webworkdocs/ and then click on Download Software and follow the instructions. You will have to register to download files. If you have difficulty registering, contact Gage or Pizer.

webwork_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz

and also:

readme.first readme.install readme.upgrade overview.html linux.html (really instructions for setting up WeBWorK on any unix system) linux-redhat-8.0.html (instructions for setting up RedHat 8.0 as a WeBWorK server)

These six files are contained in webwork_X.X_XX-MONTH-XX-XXXX.tar.gz but you should look at overview.html and readme.install for information on where to install the files. Even if you are not using RedHat, we recommend that you read linux-redhat-8.0.html as this contains useful information.

3. Unzip and untar the tar file webwork_1.8_XXX.tar.gz tar -xzvf webwork_1.8_XXX.tar.gz This will create the directory webwork_1.8_XXX containing the main webwork directory and six additional files: three readme files (readme.first, readme.install, readme.upgrade), an overview of the setup procedure (overview.html),the detailed setup procedure (linux.html), and a detailed explaination for setting up a server for WeBWorK using RedHat Linux 8.0 (linux-redhat-8.0.html). Follow the procedures in these documents.

After you set up the demoCourse, when you connect to demoCourse, you will see a link to the WeBWorK documentation. We have a lot of documentation (most of which we hope is correct). It's not that well organized so you have to hunt around for stuff. The documentation we use the most is "A DAY IN THE LIFE OF A WEBWORK PROFESSOR"

http://webwork.math.rochester.edu/docs/docs/courseadmin/usingwebwork.html

Also see the doc's on using the pg language (for writing problems)

http://webwork.math.rochester.edu/docs/docs/pglanguage/

This is a discussion group where you can ask questions and hopefully receive answers from other WeBWorK users (and or search through questions, answers, and documentation).

http://webhost.math.rochester.edu/webworkdocs/discuss/

4. We use the pg language (almost perl with some macros) for writing problems. The templates_X.X_XX-MONTH-XX-XXXX.tar.gz file contains a library approximately 2500 WeBWorK problems covering pre-calculus, first year calculus, vector calculus, differential equations, probability, and statistics. These are all written in the pg language and should serve as good examples in case you want to write your own problems. In addition you can connect to http://webwork-db.math.rochester.edu/cgi-bin/cvsweb.cgi/ and download problems written at other institutions.

5. You shouldn't really change the demoCourse (unless you are sure you know what you are doing). IMPORTANT NOTE , the (binary) databases are sytem dependent so we have not included the ones for the demoCourse in this distribution. You will have follow the instructions on initializing passwords, setting prof privileges, and building problem sets. After you have the demoCourse working, set up a new course and then play with it to your hearts content. Your demoCourse should be similar to ours: http://webwork.math.rochester.edu/courses/demoCourse . Note: the latex2html gifs for the demoCourse have not been pre created. Thus if you select "typeset" mode there will be a delay as the gifs are created on the fly (assuming everything works). Depending on your system, the actual TeX fonts may be created on the fly the first few times if TeX is new on your system. If you view the problem again, there will be no delay as the gifs are stored and reused (unless you have edited the problem template in the mean time). "typeset2" mode, which uses dvipng, is much faster than latex2html and provides the same quality images. Also you will have to install tth binary (which is needed for "formatted text" mode). Install the correct binary for your system. Directions for doing this are given in linux.html. Initially, we suggest you test things out using TEXT mode.

6. By default, WeBWorK used the gdbm database. You can also use the Berkeley db database by changing a setting in Global.pm (or in an individual course). Be warned that we have not tested things extensively with the db database. We highly reccommend you use gdbm.

7. Here is the general structure: webwork/courses contains individual courses and webwork/system contains all the common system files. The file .../system/lib/Global.pm contains defaults for the whole system. Most of these can be over ridden for a particular course in the e.g. .../courses/mth140a/webworkCourse.ph file. This file is created when you set up a new course (mth140a in the above example). As an example, $htmlModeDefault = 'Latex2HTML'; in webworkCourse.ph overrides $htmlModeDefault = 'HTML'; in Global.pm for the mth140a course. In general, the webworkCourse.ph file contains course specific information. E.g. if a prof doesn't want to use latex2html, copying

# The rendering modes for onscreen problem display which are available to the student. # Modes can be added, or commented out here. Adding a new mode required additional changes. # The format is [internal symbol, external name]. $available_mode_list = [ ['HTML', 'text'], ['HTML_tth', 'formatted-text'], ['HTML_dpng' ,'typeset2'], ['Latex2HTML', 'typeset'] ];

from Global.pm to webworkCourse.ph and then commenting out the "['Latex2HTML', 'typeset']" line will eliminate all references to "typeset" mode for his or her course. Or a prof could change the external name for a mode.

8. Different courses can use different macros for writing and answering problems. By default, all courses use the same macros found in .../system/courseScripts. One can change this in webworkCourse.ph to point to course specific macros. Look at these files especially if you want to write your own answering mechanisms and/or problem writing macros. Our hope is that this will become a little like TeX. Standard macros used by almost everybody that can be added to by individuals. The point is that one can change quite a few things without changing the system code. In practice, most users will be content to use the standard macros in .../system/courseScripts.

9. If you do try to improve the code, please inform us of any suggested changes. We certainly want to maintain one consistent WeBWorK product. The is one reason for us copyrighting the WeBWorK name.

10. Trouble shooting. The thing that causes the most problems is permissions. If you carefully follow the set up procedures, we hope you won't have problems. Also sometimes the paths to required unix programs are wrong. Again if you carefully follow the set up procedures, this should not occur. If it does, look at the messages in WeBWorK's error log (see below).

Further look in the error logs for your webserver and in WeBWorK's error log .../webwork/system/logs/error_log.

For debugging errors in output (postscript,latex2html, etc), set $imageDebugMode to 1 in Global.pm and then look at the messages in WeBWorK's error log ( .../webwork/system.logs/error_log) and in the webserver's error log. Also with $imageDebugMode set to 1 intermediate temporary files (log files, TeX files, etc) will be saved and these may help in finding the error. You will find these files in the course's tmp directory. Don't leave $imageDebugMode set to 1. If you do, you will find your file system filling up.

If you have difficulty displaying graphs look at the system dependent scripts gif2eps and png2eps in the .../webwork/system/scripts directory. Remove the -nosetpage switch which is required for some versions of pnmtops and invalid for other versions.

If you do still have trouble (especially if you see Internal Server Error), edit .../webwork/system/lib/webworkConfig.pm setting $cgiDebugMode = 1; $cgiDebugMode, when enabled, will call the debug wrapper scripts instead of the cgi scripts themselves, allowing for header output, etc. In addition to setting $cgiDebugMode =1, you will also need to enable debugging in the wrapper script for the cgi script that you wish to debug, by setting $debug = 1. Wrapper scripts are found in the directory referred to by $cgiWebworkURL, which is usually webwork/system/cgi and have the same name as the underlying cgi script.

11. Some problems have a hard coded statement that you have to get all parts correct in order to receive credit. This is not true if the partial credit problem grader is used. In general, it is better to let the software generate such statements rather than put them in problems. But we have not edited them all out. Also some problems have the statement that you have to use a * to denote multiplication. This is no longer true. A few problems have references to specific texts. They may have to be edited.

12. Initially we ran WeBWorK under IRIX on an SGI Indy. We then ran it under FreeBSD on a pentium II 400 mhz machine with about 900 students (in several classes, the largest having about 250 students). We started running into performance problems so we switched to a dual procesor pentium III 500 mhz server from Dell (cost $2,300) still using FreeBSD. That machine provided good performance. We just switched to a Dell PowerEdge 4600 with dual 2 GHz Xeon processors (cost $5,000). This is one fast machine wich is more than adequate for the 1300 students we have using the system. Others have installed WeBWorK on PC's running Red Hat Linux, Solaris, and on alpha workstations. There are well know performance problems associated with running very busy interactive web sites (and WeBWorK is highly interactive). We expect with the present software, WeBWorK will have performance problems with very large classes or on old, slow hardware. We hope to address these potential problems with a mod_perl release of WeBWorK in the future.

13. It would be very helpful to us if you could keep track of how the installation process goes and tell us about confusing instructions, errors, suggestions for improvements, etc.

Mike Gage and Arnie Pizer

<| Post or View Comments |>