Setting up a WeBWorK system

Installation

Note: root privilege are needed for some of these steps.

The "you" in these instructions refers to the person setting up the WeBWorK system. Usually this will be a system administrator using his or her non root userid.

In the file access.conf add the keyword FollowSymLinks under Options both for the document root and the cgi-bin (but note that that newer versions of Apache encourage the consolidation of the previously separate config files httpd.conf, access.conf, and srm.conf into a single httpd.conf); or

In the file httpd.conf add the keyword FollowSymLinks under Options for the document root. Also setup a ScriptAlias for WeBWorK's cgi directory and under this enable FollowSymLinks (see step 8 below). Actually, if you use the ScriptAlias method, it is not necessary to enable FollowSymLinks, but your webserver will suffer a slight performance hit if you do not.

    tar -xvf webwork.tar

It's best to not run tar as root. If you run it as root, the files will have ownerships and groups which make no sence on your system. You or root may have to temporarily change the permissions on /www so that you have write permission. This will create a new directory webwork containing two subdirectories, system and courses (each, in turn, containing their own files and subdirectories):

    webwork
        system
        courses

/www/webwork/system contains WeBWorK system files and /www/webwork/courses contains WeBWorK course files.

    chgrp -R wwadmin /www/webwork

You may see a few warning messages about symbolic links, depending on how your system's chgrp command works; these can be safely ignored.

    chmod -R 755 /www/webwork

Here is the first method. Have your system administrator (root) set up a webwork subdirectory of the web server's "cgi-bin" directory (where the web server expects to find CGI scripts). In this new webwork subdirector set up a symbolic link called system , pointing back to /www/webwork/system/cgi. In our example, we assume the server's "cgi-bin" directory to be /www/cgi-bin:

    cd /www/cgi-bin
    mkdir webwork
    chmod 755 webwork
    cd webwork
    ln -s /www/webwork/system/cgi system

Here is the second method (based on Apache). Have your system administrator (root) edit Apache's httpd.conf file adding the following code:

    ScriptAlias /cgi-bin/webwork/system/ "/www/webwork/system/cgi/"
    <Directory "/www/webwork/system/cgi">
        Options FollowSymLinks
        Order deny,allow
        deny from all
        allow from all
    </Directory>

At this point (using either method) the cgi WeBWorK URL has been defined. With the above setup, it is http://www.math.rochester.edu/cgi-bin/webwork/system where of course www.math.rochester.edu is replaced by the URL of your local web server. Remember this cgi WeBWorK URL (at least the /cgi-bin/webwork/system part) as it will be needed by the installation process below.

    cd /www/htdocs
    ln -s /www/webwork/system/system_html webwork_system_html

At this point the html WeBWorK system URL has been defined. With the above setup, it is http://www.math.rochester.edu/webwork_system_html where of course www.math.rochester.edu is replaced by the URL of your local web server. Remember this html WeBWorK URL (at least the /webwork_system_html part) as it will be needed by the installation process below.

    #!/usr/bin/perl

    #!/usr/bin/perl

    cd /www/webwork/system

and execute the setup script:

    ./system_webwork_setup.pl

(You don't need to run this command as root, but you do need to be in the wwadmin group if you're not setting up a demo version.)

You will be prompted for the following information:

• If the web server is running in a chroot environment you need to know the directory the server will see as root, for example, /www/webwork-root. If the web server is not running in a chroot environment you don't need any additional information.

   

• The path to the perl intepreter on your system, as determined above. Usually this is something like /usr/bin/perl

   

• The group set up above (e.g. wwadmin) containing the login names of anyone who has the authority to modify webwork system files. Who ever runs this script must be a member of this group. (Note: This is not required for a demo version).

   

• The cgi WeBWorK URL as determined above. Usually this is something like http://www.math.rochester.edu/cgi-bin/webwork/system . It is sufficient and preferable to enter just /cgi-bin/webwork/system but if you do this, don't forget to enter the initial "/".

   

   

• The html WeBWorK URL as determined above. Usually this is something like http://www.math.rochester.edu/webwork_system_html . It is sufficient and preferable to enter just /webwork_system_html but if you do this, don't forget to enter the initial "/".

   

• Whether to set up a "working" or a "demo" WeBWorK system. A "demo" system should only be used as a sample system, never for a system that will be used with actual courses with real students. The main difference between a "working" version and a "demo" version is that in a "working" version you will be promped to enter a group (e.g. wwadmin) where as in a "demo" version, the group will be set to your own default group (e.g. fac). Anyone in the group will have permission to modify all webwork files. You can set up "working" and "demo" courses under either a "working" or a "demo" system, but normally you would not set up a "working" course under a "demo" system.

   

Local Dependencies

On an initial installation, you can skip the changes in this section if you want. Doing so will mean that a number of things probably won't work (e.g. formatted-text and typeset output when viewing problems, hardcopy output, graphics, and feedback email). However, you will be able to test out all other aspects of the system.

Edit the files makePDF, makePS and gif2eps (which are found in /www/webwork/system/scripts). In the first two edit the paths for latex, dvips, and ps2pdf to the appropriate values for your system. These programs may need to invoke other utilities (such as GhostScript), so you may need to modify the PATH variable to include the directories where these utilities can be found. Edit gif2eps changing the PATH variable be suitable for your system.

Edit the file displayMacros.pl (in /www/webwork/system/courseScripts). In the last several lines of this script, replace /usr/bin/latex2html with the correct path to latex2html on your system. Actually there are two calls, one for latex2html version 96.1 and the other for version 98.1. One of these calls is commented out. You may also have to edit the applicable latex2html.init file (either latex2html.init.96.1 or latex2html.init.98.1) are in /www/webwork/system. Finally you may need to customize the PATH variable here as well.

Obtain a copy of tth ( http://hutchinson.belmont.ma.us/tth/ ) for your platform and place the binary tth file (named tth) in the directory /www/webwork/system/scripts. The tth file should have permission 775. You may have to compile tth for your platform but binaries are available for many operating systems. The tth binary is NOT included with WeBWorK. However, it can be obtained without cost for non commercial use from the above site. You do not have to edit WeBWorK's path to this binary (if you use the file name and directory suggested above) but just in case, the path is defined around line 352 in the tth subroutine of the file dangerousMacros.pl (in /www/webwork/system/scripts/courseScripts). The path variable is called $tthpath.

Edit the file Global.pm (which is found in /www/webwork/system ). Enter correct information for $feedbackAddress (to which WeBWorK feedback mail will be delivered).

Enter correct information for $smtpServer (which WeBWorK will use as a mail server and which you selected when you set up SMTP).

Also enter the correct information for $legalAddress and $webmaster.

File Permissions

The setup script system_webwork_setup.pl sets file permissions unless you tell it not to. Setting permissions correctly by hand can be very tricky. The main requirement is that the webserver must be able to read almost all files and directories and must be able to write to several of them. If you have permission problems, the following will certainly be sufficient to get started. (You will not want world-writable files for the long term, however.) In /www/webwork execute the command

    chmod -R 777 system

Set up the demoCourse

The demoCourse is a special course which is used both as a demo and as a template for setting up all other courses.

First, go to "base course directory" of the demo course:

   cd /www/webwork/courses/demoCourse

Now follow the instructions in "Using WeBWorK" (/www/webwork/system/system_html/docs/techdescription/usingwebwork.html), especially "SETTING UP A COURSE" (/www/webwork/system/system_html/docs/techdescription/settingupcourse.html).

Items number 1, 3 and 4 have already been done for you, but read them over nevertheless, since you'll need information gathered in them later in the installation. For item 2, a reasonable URL for the demoCourse would be http://www.math.rochester.edu/demoCourse. Also, in step 6, you won't need to copy any files (they are already here), but you must run the course setup script course_webwork_setup.pl in step 8. When running course_webwork_setup.pl, (a) choose to setup a "working" version; (b) use "demoCourse" as the classID; and (c) answer yes (y) to all questions.

Here are precise instructions:

We need to setup a special group for people who have permisson to read from and write to files associted with the demoCourse. In addition we have to add the webserver to this group since the webserver also needs permission to read to and write from these files. Our normal convention is that if the name of a course is e.g. mth100, we call the group MTH100 (both course and group names are case senitive). So we will use DEMOCOURSE as the group name.

Note that there are precise instruction in webwork_linux_redhat3.1_setup and you should look at these.

Enter the following commands:

From the demoCourse directory

./course_webwork_setup.pl

Hit [Enter]
enter y
enter w (to set up a working version)
enter y
Hit [Enter]
Hit [Enter]
Hit [Enter]
enter DEMOCOURSE (as the name of the group)
enter y
enter y
enter y
enter y

This script should complete with a list of things you are asked to read about. Now we have to issue some WeBWorK commands. The easiest way to do this is to put

.../webwork/system/scripts/ in your search path. I will assume you have done this.

Now enter

cd .../webwork/courses/demoCourse/templates

NOTE: You do not have to work from this directory. But if you do you can
use [Tab] completion and using this makes it less likely that you will make a
mistake. If you just enter a command name, e.g. initialPasswords.pl, you
will be told the correct syntax to use. The coursename which follows a command
(e.g. initialPasswords.pl) determined which course you are acting on. Be
careful to type the correct name especially if you have permission to edit
files for many courses. In what follows if you enter initi[Tab]de[Tab] you
will see initialPasswords.pl demoCourse.lst This tells you you are working
with the correct course. Now just use the Backspace key to remove the .lst,
enter <space>de[Tab] and you are ready to go. So now enter(using [Tab]
completion)

import_classlist-database.pl demoCourse demoCourse.lst

Now enter (using [Tab] completion):

setProfPermissions.pl demoCourse apizer

You should see a listing of permissions with apizer having permission 10.

Now you are ready to login to demoCourse. Connect to the demoCourse URL You should see the login page. If you do not, check the webservers error log. (The full URL is .../demoCourse/index.html)

login as user: apizer with password 111-11-1111 (don't foget the dashes)

Click Enter Professor's Page

Click Enter Build Problem Set Page (the only choice you should see)

Select all the sets and then click Build Problem Set(s) You will see a list of the sets which have been built. Now build some problem sets. You will see a list of the sets which have been built. At the bottom of the page click Problem Sets

Select a set, e.g set Algebra1RealNumbers, select PDF form, and click Get_Hard_Copy. After a short wait (since this is the first time TeX has probably been run, fonts may have to be created, etc), Acobat should start and you should see a copy of the set. You can select postscript output if your client computer can display that (e.g using Ghostview). Note: the first few times you use Get_Hard_Copy it may take quite some time as the computer probably has to run Metafont to create TeX fonts. The second time you run Get_Hard_Copy on the same problem set will give you a better idea of how fast your system will usually respond.

Next click Do Problem Set and view a few problems. Use the selected mode which, at present, is TEXT which means TeX source code. Next for say problem 2, select "formatted-text", and hit submit answers. This uses tth and which should be working. With this mode math symbols appear on the screen composed of ascii characters. Note "typeset" mode will not be working yet. Go to problem 10, enter 12/23 and hit Preview Answers. You should see the type set fraction 12 over 23.

At this point you should have a functioning course. You can login as a practice user (username practice1, ..., practice4), apizer with password 111-11-1111, gage with password 444-44-4444, etc. All usernames and initial passwords are lised in /www/webwork/courses/demoCourse/templates/demoCourse.lst. The first entry of a record is the userid which is the initial password and the last entry of a record is the username. Actually the users are taken from the classlist database which you can view from the Classlist page.

Note that demoCourse is a dynamic functing course. Since this is used as a template to setup other courses, you may want to copy demoCourse into a new course, say templateCourse, check that templateCourse functions properly, and then freeze it (turning it into a non functioning course) by doing a chmod -R 444 templateCourse . That way you could use the templateCourse in setting up new courses and you will know that it has not been changed by any users.

There are a few other changes you may want to make.

1. Arround line 69 you may want to comment out use diagnostics;. Leaving this uncommented will mean that various warning messgaes will be displayed. In general, its good to see such warning messages but it's your choice.

2. Arround line 333 you will probably want to change $htmlModeDefault = 'HTML';. This sets the default display mode for problems (either 'HTML' (text), 'HTML_tth' (formatted text) or 'Latex2HTML' (typeset)). This can be changed for individual courses. 'HTML_tth' is a good choice for the default mode. Students can choose whatever mode they want, but the default mode is what they will get if they don't make a choice. 'HTML' (text) mode is raw TeX code so you probably don't want to make that the default.

3. You might want to quickly skim the Global.pm so that you can see what other defaults can be changed. Most likely, you will choose to keep most defaults unchanged.

<| Post or View Comments |>