Forum archive 2000-2006

Michael Gage - Installing WeBWorK

Michael Gage - Installing WeBWorK

by Arnold Pizer -
Number of replies: 0
Installing WeBWorK topic started 4/26/2000; 10:25:42 PM
last post 4/26/2000; 10:25:42 PM
userMichael Gage - Installing WeBWorK  blueArrow
4/26/2000; 10:25:42 PM (reads: 1218, responses: 0)

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.

 

First read An Overview of the setup procedure for information on where to install the WeBWorK files, how WeBWorK interacts with the webserver, and what the system and course setup scripts do. Then read the readme.install file before you begin.

Have your system administrator (root) set up a both a new user and group (e.g., the name wwserver could be used for both), and modify the web server's configuration files to make it run as this user and group; with the Apache server you'll need to set the User and Group variables in httpd.conf. Also make sure your server is configured to follow symbolic links under the document root and under the cgi-bin; with Apache (depending on the version) either:

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.

 

Have your system administrator (root) set up a special group (e.g. wwadmin) containing the user names of anyone who has the authority to modify webwork system files. You'll need to be a member of this group to setup WeBWorK later. Remember this group name as it will be needed by the installation process below. Note: Setting up a special group is not required for a demo version but is recommended anyway. You may need to log out and log back in again for the changes to take effect.

 

Now, decide where to put your base WeBWorK directory (see step 1 above). In a chroot environment we would place this in /www/webwork-root. In a non chroot environment we would place it in /www. We will use the non-chroot example for the following instructions. You'll need to replace "/www" in the following examples with the directory that you've chosen to contain WeBWorK, e.g. /home/httpd in a typical linux setup.

 

Copy the archive webwork.tar into the /www directory and untar it with the command:

 

    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.

 

Execute the following command to set the proper group ownership of the WeBWorK 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.

 

Execute the following command to make sure you have write permission for all the WeBWorK files and to correctly set the permissions for the upper level directories. This is needed in order to run the system_webwork_setup.pl script later. That script will set individual permissions and groups for most files and directories.

 

    chmod -R 755 /www/webwork

 

 

There are two methods for connecting WeBWorK's cgi directory to the webserver.

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.

 

 

In your webserver's document root (often a directory called "htdocs" or "html") have your system administrator (root) set up a symbolic link called webwork_system_html pointing back to /www/webwork/system/system_html. In our example, we assume the server's "htdocs" directory to be /www/htdocs:

 

    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.

 

 

You will need to run the system_webwork_setup.pl script, which is in the /www/webwork/system directory. First, however, you will also need to know the path to the the perl interpreter on your system (usually something like /usr/bin/perl or /usr/local/bin/perl). Edit the first line of system_webwork_setup.pl, replacing (if necessary)
    #!/usr/bin/perl
by
    #!/usr/bin/perl
or whatever is correct for your system. Remember the path to perl as it will be needed by the installation process below.

 

You are now ready to run the system_webwork_setup.pl script. Make sure you are in the /www/webwork/system directory:

 

    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. The tth binary included with WeBWorK runs on Linux. You should 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). Also on the line that reads:

 

    $SENDMAIL       = '/usr/sbin/sendmail -t -oi -n';

replace /usr/sbin/sendmail with the path to sendmail on your system. (It's often in /usr/lib.) If you use a Mail Transfer Agent other than sendmail, you'll need to change the arguments passed (-t -oi -n) as well.

 

Edit the file feedback.pl (which is found in /www/webwork/system/cgi/cgi-scripts ). Enter correct information for $WEBMASTER and $SMTP_SERVER.

 

Finally edit the file PGtranslator.pm (which is found in /www/webwork/system ). Around lines 1136-37 enter correct information for $WEBMASTER and $SMTP_SERVER.

 

 

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.

 

Pay particular attention to the following instructions from "SETTING UP A COURSE":

 

NOTE: If you have just setup the WeBWorK system and are now setting up the demoCourse, the copied databases may not work on your possibly different architechure (or the databases may be missing) and you may not have a working setup at this point. In that case follow the instructions in the next paragraph.

If you want to start with a totally new course cd to DATA and remove all files there (rm *) . Then cd to .auth and remove all files there (rm *) . If you don't remove the files in DATA and DATA/.auth , you will have four practice users and a number of other users (look at mth140a.lst in templates). Also for a totally new course remove all the temporary LaTeX2html files and directories. To do this, remove everything from MTH140A/html/tmp/l2h/

    cd /www/webwork-root/webwork/courses/MTH140A/html/tmp/l2h
rm -rf *
Finally for a totally new course remove all the scoring files (if any) from MTH140A/scoring/
    cd /www/webwork-root/webwork/courses/scoring
rm *

 

Then follow the instructions in "Using WeBWorK" ... for "INITIALING PASSWORD AND PERMISSIONS" and "CREATING A PROBLEM SET". In these instructions, substitute "demoCourse" for "MTH140A" and "demoCourse.lst" for "mth140a.lst.

 

Specifically, enter the following commands:

 

initialPasswords.pl demoCourse demoCourse.lst  
setProfPermissions.pl demoCourse apizer

Now you are ready to login to demoCourse. Connect to the demoCourse URL and login as apizer with password 111-11-1111 (don't forget the dashes).

You will see an option to go to the Professor's page. Go there. At this point the only option you will see is to go to the build problem set page. Go there. Now build some problem sets. Then use the up buttons to return to the first (welcome) page and select Begin Problem Set.

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.

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.

 

Customize the Global.pm file

The Global.pm file is contained in the /www/webwork/system directory. It contains defaults and parameters for the whole WeBWorK system. Many of these defaults can be over ridden for individual courses in the webworkCourse.ph file.

Around lines 45-55 in Global.pm make the following changes:

  1. Change $webworkDocsURL = 'http://webwork.math.rochester.edu/docs/'; to point to your local WeBWorK documentation URL. Actually, you can leave this as is and then links to the documentation will point to rochester.edu. For greater efficiency, point this to the WeBWorK documentation on your local system. Do this as follows. In your webserver's document root (often a directory called "htdocs" or "html") have your system administrator (root) set up a symbolic link called docs pointing to /www/webwork/system/system_html/docs. In our example, we assume the server's "htdocs" directory to be /www/htdocs:

     

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

    At this point your local WeBWorK documentation URL has been defined. With the above setup, it is http://www.math.rochester.edu/docs where of course www.math.rochester.edu is replaced by the URL of your local web server. In Global.pm replace 'http://webwork.math.rochester.edu/docs/'; by your local WeBWorK documentation URL.

  2. Change $feedbackAddress = 'webwork@math.rochester.edu'; to some default address. This is a default address for student feedback in case the $feedbackAddress for an individual course has not been set in the webworkCourse.ph file. This should be set in the individual webworkCourse.ph files to point to professors and/or TA's for the individual courses.

  3. Change $legalAddress = '^w+(@(w+.)*rochester.edu)?$'; so that it is correct for your system. This is used by /www/webwork/system/cgi/cgi-bin/development/feedback.pl.pl.

  4. Change $webmaster = 'webmaster@math.rochester.edu'; so that it is correct for your system.

  5. Change $sendMail = '/usr/sbin/sendmail -t -oi -n'; so that it is correct for your system. Replace /usr/sbin/sendmail with the path to sendmail on your system. (It's often in /usr/lib.) If you use a Mail Transfer Agent other than sendmail, you'll need to change the arguments passed (-t -oi -n) as well.

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 |>