Installing WeBWorK on a Linux System

For WeBWorK version 1.9
Samuel Hathaway <sh002i@math.rochester.edu>;
Arnold Pizer <apizer@math.rochester.edu>;

This document will guide you through the installation of WeBWorK and its support packages. We assume the reader has prior experience with UNIX system administration tasks such as compiling software, configuring the Apache server, etc.

Usually the installation of WeBWorK proceeds without difficulty. If there is difficulty, almost always it involves the installation of required packages (apache, perl and perl modules, latex2html, dvipng, etc.) rather than WeBWorK itself. While all required packages are standard and well supported, there are a lot of dependencies and problems can arrise. The document Installing WeBWorK on a Red Hat Linux 9.0 System gives detailed instructions for that system and might provide useful hints for other systems.

If you do not want to follow the instructions below, Bill Ziemer <wziemer@csulb.edu>; has posted a makefile which will install a separate configured copy of all required packages on your system. Connect to <a href="http://http://webwork-db.math.rochester.edu/cgi-bin/cvsweb.cgi/">http://webwork-db.math.rochester.edu/cgi-bin/cvsweb.cgi/, select the CVS Root CSLB and download webwork_VERSION_SUBVERSION-MONTH-DAY-YEAR_install.tar.gz.

Most steps in the installation process can be done as a normal user. However, some steps must be done as the root user. While attempts have been made to minimize the number of commands that must be executed as root, it is still important to be cautious whenever using the root account.

Within this document, commands given by root will be prefixed with "#" while commands given by a normal user will be prefixed with ">". Note that throughout this document, all references to a "normal user" refer to the same normal user. If you have sudo installed, it is recommended that you use it for the root commands. Otherwise, leave two terminal windows open one as root and one as a normal user.

Step 1: Installing perl

On many Linux distributions, the distribution version of perl is not adequate for use with WeBWorK. Specifically, perl must be compiled with GDBM database support. Whether this is so can be determined in one of two ways:

For static linkage, check the libs= line in the perl version information. You should see an item -lgdbm. For dynamic linkage, check the output of ldd for perl. You should see an item libgdbm.

> perl -V | grep libs=
    libs=-lm -lc -lcrypt

In this case, libm, libc, and libcrypt are compiled into perl.

> ldd `which perl`
/usr/bin/perl:
        libperl.so.3 => /usr/lib/libperl.so.3 (0x28066000)
        libm.so.2 => /usr/lib/libm.so.2 (0x280fe000)
        libcrypt.so.2 => /usr/lib/libcrypt.so.2 (0x28119000)
        libmd.so.2 => /usr/lib/libmd.so.2 (0x2812e000)
        libc.so.4 => /usr/lib/libc.so.4 (0x28138000)
        libutil.so.3 => /usr/lib/libutil.so.3 (0x281cd000)

In this case, libperl, libm, libcrypt, libmd, libc, and libutil are linked to perl.

If GDBM is not present in either of these outputs, perl needs to be recompiled with GDBM support. The perl compilation process will automatically compile GDBM support if the GDBM libraray is detected. Most Linux distributions come with the GDBM library. It is called libgdbm and is usually found in /usr/lib or /usr/local/lib. If you need to install the GDBM library, it is available at <a href="http://www.gnu.org/software/gdbm/">http://www.gnu.org/software/gdbm/. Please refer to the perl source code distribution site at <a href="http://www.perl.com/">http://www.perl.com for information about compiling and installing perl (click on Downloads, Source Code). Hint: get the stable.tar.gz file, extract it with the command

tar -xzf stable.tar.gz

Please note that if you recompile perl, you may have to be careful about maintaining two copies of perl on your system. When you set up WeBWorK, the setup script will try to guess where your perl is. However, it may guess the "old" version of perl if it comes before the "new" one in your path. Make sure the correct path to perl is used when setting up WeBWorK. For convenience, you may want to remove the original version of perl. The perl install process will ask you if you want to do this.

Step 2: Installing additional packages

You now have to install additional perl modules needed for WeBWorK. These are HTML::Parser, Net::SMTP, MIME::Base64, GD, and Time::HiRes. You can use CPAN to install the these. However the GD.pm module installed by CPAN requires version 2 of the gd graphics library. Often the version of gd distributed with linux is 1.8.4 or earlier. We recommend that you install version 2.0.15 of gd but you could also use e.g. version 1.8.4 and then go to http://stein.cshl.org/WWW/software/GD/old and grab GD-1.43.tar.gz and install it by hand. If you need to install version 2.0.15 of gd do so now (download it from http://www.boutell.com/gd) and look at the instructions in Installing WeBWorK on a Red Hat Linux 9.0 System if you need help.

If this is the first time you're run CPAN, you will be asked to configure it (you can say "no" and it will autoconfigure). As root, run the command

# perl -MCPAN -e shell
cpan> install HTML::Parser Net::SMTP MIME::Base64 GD Time::HiRes

If there are prerequisites which need to be installed, allow CPAN to "prepend prerequisites to the installation queue". CPAN may prompt you for configuration settings for the modules you are installing.

Sometimes a module may not install properly. To verify that a module, e.g. Net::SMTP, has been installed successfully run the the command

> perl -MNet::SMTP -e 'print "installed\n"'

You should get the message:

installed

if Net::SMTP was installed successfully and an error message if it was not.

If you get an error message, you can force an install by using the commands

# perl -MCPAN -e shell
cpan> force install Net::SMTP

This may or may not be appropiate depending on what the problem is. For example, at one time (Fall 2001) the installation Net::SMTP failed because it tested for components that were not part of the installation package. In this case the appropiate solution was to use force.

In a similar manner, you can test whether the other modules HTML::Parser, MIME::Base64, GD, and Time::HiRes were installed successfully. If you do not run these tests now, at least remember them in case you get error messages concerning modules later.

Next, you will need to install several support programs used by WeBWorK. Most distributions include packaged versions of these programs, but they are not always installed by default. Consult the documentation for your distribution to find out if you can use a prepackaged version. If you wish, you can also install from source:

• Apache: http://httpd.apache.org/
• Ghostscript: http://www.cs.wisc.edu/~ghost/
• LaTeX2HTML: http://www.latex2html.org/
• Netpbm: http://netpbm.sourceforge.net/
• teTeX: http://www.tug.org/teTeX/
• dvipng: http://hobbes.la.asu.edu/webwork-stuff

LaTeX2HTML

LaTeX2HTML is necessary to use the 'typeset' display mode when viewing problems on the screen. If you're just evaluating WeBWork or don't wish to use 'typeset' mode, you can skip this section.

LaTeX2HTML has some dependancies of its own. Consult the LaTeX2HTML Requirements Page at http://www- texdev.mpce.mq.edu.au/l2h/docs/manual/Snode2_mn.html for more information.

Only LaTeX2HTML version 96.1 and 98.1p1 have undergone extensive testing with WeBWorK. WeBWorK ships with latex2html.init files for each if these versions. However, the init file for version 98.1p1 appears to work with later versions.

LaTeX2HTML may be broken with respect to the WeBWorK system when installed. To fix it, make sure the following configuration variables are set as follows in the LaTeX2HTML configuration file, which may be called latex2html.config or l2hconf.pm and may be located in /etc or in the LaTeX2HTML directory, depending on the version and how it was installed.

$PK_GENERATION = 1
$DVIPS_MODE    = 'toshiba'
$METAFONT_DPI  = 180

Netpbm

Netpbm versions before 9.11 cause black borders to appear to the left of and below images generated by LaTeX2HTML. To fix this, apply the patches detailed at: http://tug.org/pipermail/latex2html/2001- May/001112.html

TTH

WeBWorK uses TTH, a C program which typesets TeX as HTML, using tables and other markup. TTH is necessary to use the 'formatted-text' display mode when viewing problems on the screen. If you're just evaluating WeBWork or don't wish to use 'formatted-text' mode, you can skip this section.

TTH cannot be distributed with WeBWorK because of licencing issues. It can be obtained from <a href="http://hutchinson.belmont.ma.us/tth/">http://hutchinson.belmont.ma.us/tth/ . If you can, download a precompiled binary. Otherwise, download the source and the following other packages:

• C libarary headers: http://www.gnu.org/software/libc/
• GCC: http://gcc.gnu.org/

As a normal user, download TTH to your home directory. Then untar, build, and install it with the following commands:

> tar -xzf tth_C.tgz
> cd tth_C
> gcc -o tth tth.c

Then, as root, install it.

# cp tth /usr/bin/

dvipng

dvipng is necessary to use the 'typeset2' display mode when viewing problems on the screen. If you're just evaluating WeBWork or don't wish to use 'typeset2' mode, you can skip this section.

dvipng produces typeset images identical in quality to those produced by LaTeX2HTML. It is much faster than LaTeX2HTML and WeBWorK will use it in place of LaTeX2HTML in the future. It has been extensively tested with WeBWork by many large sites this past year. We strongly recommend installing it and using it as the default viewing mode. For information on obtaining and installing dvipng visit John Jones's site <a href="http://hobbes.la.asu.edu/webwork-stuff">http://hobbes.la.asu.edu/webwork-stuff . Also look at the detailed information on dvipng in Installing WeBWorK on a Red Hat Linux 9.0 System.

Step 3: Configuring apache

Note: Since the locations of apache's document root and cgi- bin directories are distribution dependant, I will use $DOCUMENT_ROOT and $CGI_BIN to refer to these locations. The actual locations are defined in the apache configuration file, see below. If you wish, you can set these two variables in your shell so that you can type them directly.

Your apache configuration may need to be tweaked to allow WeBWorK to function properly. First, you must make sure that apache runs as a real system user and in a real system group, rather than as nobody in nogroup. This is becasue the WeBWorK scripts need to be able to modify certain course files on the disk. Some distributions of apache already run as a real system user. If so, you may skip the creation of a new user and group, and use the existing ones. If you need to change apache's user and group, first create a new user and group called wwserver:

# useradd wwserver
# groupadd wwserver

Then, in the apache configuration file httpd.conf, usually found in /etc/apache or /usr/local/etc/apache, find the following lines:

User nobody
Group nogroup

Change them so that they list wwserver as the user and group:

User wwserver
Group wwserver

There are two ways that the webserver can be given access to WeBWorK files. The first is to add an explicit ScriptAlias to the WeBWorK cgi directory in your apache configuration (this is the method we recommend). The second is to create a symlink pointing from your existing cgi-bin directory to the WeBWorK cgi directory. If you chose to use symlinks, you will have to make sure that the FollowSymLinks option is on for the document root and cgi-bin directories.

In either case, your document root must have FollowSymLinks turned on. In one of your apache configuration files, find the directory stanza for the document root. It will look roughly like this:

<Directory $DOCUMENT_ROOT>
	Options FollowSymLinks Indexes Includes
	AllowOverride None
	Order allow,deny
	Allow from all
</Directory>

The important line is Options FollowSymLinks. Make sure that that is present. It is okay if other options are present too. If you chose to symlink to the WeBWorK cgi-bin directory, also make sure that the directory stanza for your cgi-bin directory has FollowSymLinks turned on:

<Directory $CGI_BIN>
	Options FollowSymLinks ExecCGI
	AllowOverride None
	Order allow,deny
	Allow from all
</Directory>

If you chose to use a ScriptAlias to link apache to the WeBWorK cgi-bin directory, you will need to add the following to your apache configuration:

ScriptAlias /cgi-bin/webwork/system/ "/usr/local/webwork/system/cgi/"
<Directory /usr/local/webwork/system/cgi/>
	Options ExecCGI
	AllowOverride None
	Order allow,deny
	Allow from all
</Directory>

Make sure that these lines go before any existing ScriptAlias directives. Remember to restart apache after making these changes.

Step 4: Installing the WeBWorK package

WeBWorK can be downloaded from following URL: http://webhost.math.rochester.edu/downloadwebwork/ . Click on the Download Files link on the left side panel.

If you haven't already, you need to register to be able to download files. The WeBWorK archives are named in the following form:

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

The webwork archive contains the webwork system files and the blankCourse. The templates archive contains the problem set templates, and is updated more often than the webwork archive is.

As a normal user, download the latest versions of the webwork archive. Untar the WeBWorK archive using:

> tar -xzf webwork_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz
(replacing the file name with the file you actually have.)

This results in the creation of a webwork_VERSION_SUBVERSION-MONTH-DAY-YEAR directory which contains several readme files and the webwork directory, which contains the actual webwork system. First cd to the new directory

cd webwork_VERSION_SUBVERSION-MONTH-DAY-YEAR

# mv webwork /usr/local

The WeBWorK files are now in their initial location. Next, a user group must be created for users who are allowed to modify all WeBWorK files. It is recommended that this group be named wwadmin. As root, execute:

# groupadd wwadmin
# usermod -G wwadmin,<othergroups> <username>

Note: The usermod command will remove a user from any groups not specified with the -G switch. Make sure to list all the groups to which a user belongs when using this command. This manual uses user{add,mod,del} and group{add,mod,del} as these utilities are available on most linux systems. It is often easier to use a more user-friendly tool provided with your distribution. Older versions of Red Hat provide linuxconf, which may not be installed by default. New versions have the Red Hat User Manager. Debian provides adduser and addgroup.

You can add any number of users with the second command, replacing <username> with the name of the user to add. Make sure that you add the user account that you are going to be using to finish setting up the system.

We'll make a webwork directory in apache's document root to contain a symlink to each course. We'll also give you ownership of this directory so you can add courses later without becoming root. We will also change permissions so that any user in the group wwadmin can do the same. As root, type the following:

# mkdir $DOCUMENT_ROOT/webwork
# chown <username>.wwadmin $DOCUMENT_ROOT/webwork
# chmod 775 $DOCUMENT_ROOT/webwork

If you chose not to add a ScriptAlias directive to your apache configuration, you also need to add a webwork directory to apache's cgi-bin directory.

# mkdir $CGI_BIN/webwork
# chown <username>.wwadmin $CGI_BIN/webwork
# chmod 775 $CGI_BIN//webwork

We need to allow apache access to WeBWorK's html directory. As root, type:

# ln -s /usr/local/webwork/system_html $DOCUMENT_ROOT/webwork_system_html

Again, if you didn't add a ScriptAlias directive to your apache configuration, you also need to allow apache access to WeBWorK's cgi directory:

> ln -s /usr/local/webwork/system/cgi $CGI_BIN/webwork/system

The next step uses your normal user account, and requires membership in the wwadmin group. Thus, you'll need to log out of this account and then log back in. Depending on your setup, you may have to log out of X for changes to take effect. Next, we'll set the group of the entire WeBWorK system to wwadmin and give it some default permissions. As a normal user:

> chgrp -R wwadmin /usr/local/webwork/
> chmod -R 775 /usr/local/webwork/

These permissions are very lax, but that will be fixed when we run the setup script. As a normal user:

> cd /usr/local/webwork/system
> perl system_webwork_setup.pl

This script will ask you several questions about the environment in which WeBWorK will be running. Read the information given with each choice carefully. Recommended choices are given in brackets, and can be accepted by pressing enter rather than typing a response.

Now we need to run one more script which will create needed links. As a normal user:

> cd /usr/local/webwork/system/courseScripts/
> perl MAKELINKS.pl

In order to use logging, you need to give the web server write access to the logs directory and its files . As root:

# chgrp -R wwserver /usr/local/webwork/system/logs

Check that the path to the various Netpbm utilities are correct in the two shell scripts gif2eps and png2eps which are located in the /usr/local/webwork/system/scripts/ directory. You may have to modify NETPBM which is set to /usr/bin. Use which giftopnm, for example, to determine the location of the giftopnm binary. If you have trouble displaying graphs, read the comment in both these shell scripts concerning the -nosetpage switch.

There are some user-definable settings that you should customize in the file Global.pm. This file is located at: /usr/local/webwork/system/lib/Global.pm

################################
# Local configuration settings #
################################

$legalAddress
A perl regular expression which email addresses must in order
to be considered valid. By default, this is set to accept any
string as a valid email address. However, you may wish to
set this to something less permissive.
$webmaster
The address of the WeBWorK webmaster.
$smtpServer
Your sendmail server. It should usually be set to 'localhost'
unless your sendmail server resides on another machine. In
that case, specify another server.
$dirDelim
The character which separates directories in a path name.
For UNIX systems this should be set to "/".

###########################
# Local external programs #
###########################

$externalTTHPath
$externalDvipngPath
$externalLaTeX2HTMLPath
$externalLatexPath
$externalDvipsPath
$externalGsPath
These define the locations of the 'tth', 'dvipng', 'latex2html',
'latex', 'dvips', and 'gs' programs, and are set to /usr/bin/tth,
etc. by default. Use `which latex', for example, to determine the
location of the latex binary.

$dvipngMode, $dvipngDPI, $dvipngScaling, and $dvipngShrinkFactor
These control the fonts produced by dvipng. Other than possibly trying
ljfivemp, you probably should not change these unless you know what you
are doing.

$externalLaTeX2HTMLVersion
The version of LaTeX2HTML installed. This controls what
switches are sent to the program. For version 98.1p1 or
later, use "98.1p1". For earlier versions, use "96.1".
$externalLaTeX2HTMLInit
The path to the LaTeX2HTML init file. You can leave this
as is.

$extendedPath
The path to support binaries required by LaTeX, etc. The given path
':/usr/bin:/usr/local/bin' should work in most cases.

#####################
# Display Modes #
#####################

$available_mode_list
Comment out any display modes that you do not want available to students. You can also
edit the external name of a mode but do not change the internal symbol. All modes
except HTML (which is not very useful) require additional software to be installed

see Step 2 above.
$htmlModeDefault
Set this to one of the following:
'HTML' for raw TeX display of equations (not recommended for a working system)
'HTML_tth' for formatted HTML (fast but sometimes ugly)
'Latex2HTML' for image equations (pretty but slow unless cached images are precreated)
'HTML_dpng' for image equations (same quality output as Latex2HTML and as fast
as tth. This is our recommended choice.)

# When first testing a new system, you may want to keep $htmlModeDefault set to 'HTML' but
# for a working sytem, we strongly recommend you set this to 'HTML_dpng'.

#####################
# Internal settings #
#####################

$logAccessData
If you would like to log all studnet actions on your
system, set this to 1, otherwise leave it at 0.
$psvn_digits
This is usually safe to leave at 6, but read the comments
above it in Global.pm for more information.

Many other configuration settings live in Global.pm. We suggest that you read through the entire file. Note that the settings in Global.pm provide system wide defaults that apply to all courses. All of these settings can be changed for individual courses by redefining them in the individaul course's webworkCourse.ph file. After you configure Global.pm to your satisfaction, you are done with the WeBWorK system setup.

Step 5: Installing the problem set template files

Before WeBWorK can be functional, problem set template files must be present. Download the templates archive from the WeBWorK web site, as you did with the WeBWorK archive.

templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz

Move (or copy) the templates archive to the WeBWorK directory and untar it.

> mv templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz /usr/local/webwork
> cd /usr/local/webwork
> tar -xzf templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz
> mv templates_VERSION_SUBVERSION-MONTH-DAY-YEAR/templates .
> rmdir templates_VERSION_SUBVERSION-MONTH-DAY-YEAR
> rm templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz

Set the permissions on the new directory.

> chgrp -R wwadmin templates
> chmod -R 775 templates

The problem set templates are not accessed directly from this location. They are instead copied into each course which is created. This allows professors to modify their local copies without disturbing other courses.

The templates tar.gz archive is updated usually once ot twice a year. If you want to keep current with new and revised problems, you should download the problem library from our CVS respository http://webwork3.math.rochester.edu/cgi-bin/viewcvs.cgi/. See http://webwork3.math.rochester.edu/cvs.html. for instructions on downloading.

Step 6: Creating a course

Now would be a good time to add the scripts directory to your search path, so that you don't have to type the full path of the command each time. If you are using bash, add this line to the bottom of the .bash_profile file in your home directory:

PATH="/usr/local/webwork/system/scripts:${PATH}"

Log out and log back in again to add the new path. Depending on your setup, you will probably have to out of and back into X windows for changes to take effect. Type echo $PATH to check that the path has been set properly.

To test your installation of WeBWorK, you must now create a course. The base you will use to create this course is located in /usr/local/webwork/courses/blankCourse. The course we are going to create now will be called demoCourse.

Each course has a UNIX user group associated with it. The group should contain any users who should be able to view or edit the course files directly (such as the professor and any teaching assistants), and the system user under which the web server runs, wwserver. The convention on Rochester's installation of WeBWorK is to name each group after the course it represents, only using capital letters. However, some Linux distributions disallow uppercase group names. Use your own judgement.

As root, create a group for demoCourse and add yourself and the web server to it. Since we're adding the web server to a new group, we have to restart it:

# groupadd DEMOCOURSE
# usermod -G DEMOCOURSE,<othergroups> wwserver
# usermod -G DEMOCOURSE,<othergroups> <username>
# apachectl restart

Now, log out of your normal user account and log back in so that your group membership will be recognized.

Next, you will need to make a copy of blankCourse called demoCourse and add some problem set templates to it. As a normal user:

> cd /usr/local/webwork/courses
> cp -R blankCourse demoCourse
> cd demoCourse/templates
> cp -R /usr/local/webwork/templates/set0 .
> cp /usr/local/webwork/templates/set0.def .

Repeat the last two commands for any other sets you wish to import into the demo course. A popular option is to import all of the sets. To do this, type:

> cp -R /usr/local/webwork/templates/set* .

WeBWorK comes with a script which completes the setup of a new course. We'll run it now, as a normal user:

> cd /usr/local/webwork/courses/demoCourse
> course_webwork_setup.pl

This script will ask you several questions about the environment in which the course will be used. Read the information given with each choice carefully. Recommended choices are as follows:

Q: Do you wish to setup a "working" or a "demo" version? (w or d)
A: w
Q: Do you want to create missing directories (if any)? (y or n)
A: y
Q: ENTER course URL
A: press ENTER to accept the default /webwork/demoCourse
Q: ENTER cgi WeBWorK URL
A: press ENTER to accept the default /cgi-bin/webwork/system
Q: ENTER course link (i.e. classID) name
A: press ENTER to accept the default demoCourse
Q: ENTER group name
A: DEMOCOURSE (or whatever group you set up)
Q: Do you want to create a new webworkCourse.ph...?
A: y
Q: Do you want to create a new index.html...?
A: y
Q: Do you want to set the group for all directories and files?
A: y
Q: Do you want to set default "working" permissions for all directories
   and files?
A: y

We'll now make the template directory setgid so that new problems and problem sets will get the correct group and permissions.

> chmod g+s templates

To let the WeBWorK system know that it has a new course, add a symlink to demoCourse in the system/courses directory. If you do not do this, the WeBWorK system will not be able to access the course this is a good way to "turn off" a course.

> ln -s /usr/local/webwork/courses/demoCourse /usr/local/webwork/system/courses/

Each course has a "visible" interface in the webwork directory on the web server's document root. This allows the course home page to be accessed via http://servername/webwork/courseName/ rather than having to call the login script directly. As a normal user, create this link:

> ln -s /usr/local/webwork/courses/demoCourse/html $DOCUMENT_ROOT/webwork/demoCourse

Now, we're going to run some scripts to finish setting up the course. As a normal user:

> cd /usr/local/webwork/courses/demoCourse/templates
> import_classlist-database.pl demoCourse defaultClasslist.lst
> setProfPermissions.pl demoCourse professor

There. You've finished the demoCourse setup. The process for setting up additional courses is identical to this except that usually you copy the demoCourse which copies the classlist database and allowed a professor to log in and import classlists, etc. via the web. To verify that you've set everything up properly, view the following URL in your browser: http://your.server.name/webwork/demoCourse/

Note that the "trailing slash" is required unless redirects work on your server.

You should see your newly-generated course index page. If this works, click the Login button and enter the following information:

login:    professor
password: 111-11-1111

Even though this is only the demo course, it's a good idea to change your password to prevent unauthorized access.

You should be logged in as the professor. This means you will see a link for Click Enter Professor's Page. Click on it.

Before you do anything, you have to build some sets. This will test to make sure that all of the problem rendering methods work. First, click Build and Edit Problem Sets which should one of three active options. Then, select one or more problem sets from the list and click Build Problem Set(s). WeBWorK will report that the problem sets have been built. At the bottom of the resulting page, click Problem Sets.

Now that the sets have been built, you can test various methods of displaying them. Note that the first few times you display problems the system may take an unusually long time since it may have to run Metafont to create LaTeX fonts. Select a set, select PDF form and click Get_hard_copy. After a moment, WeBWorK will send you a PDF file. Acrobat may open automatically, or you may have to wrestle with your browser a bit to see it. If there are problems displaying images or hardcopy, try setting $imageDebugMode to 1 in Global.pm.

Next, we can check onscreen display. Select a problem set and click Do_problem_set. View several problems from the set on all four display modes: text, raw TeX source code, formatted- text, TTH output, typeset2, dvipng output and typeset, LaTeX2HTML output. Typeset mode takes quite some time on the first view of any problem as it has to generate images for the equations. However, subsequent views take advantage of cached temp files.

Return to the Professor's Page and now you will see a large number of utilities which you can use in administering a weBWorK course.

Step 7: Customizing the course set up

This is unecessary for the demoCourse but is something that should be done for regular courses. Edit the file /usr/local/webwork/courses/demoCourse/webworkCourse.ph entering the correct data. At the very least you should enter data for

$Global::feedbackAddress
$smtpSender
$PG_environment{'PRINT_FILE_NAMES_FOR'}

Step 8: Separating Static and Variable WeBWorK data

Right now, all WeBWorK files are located under /usr/local. While this is the simplest setup, it is not the best way to do things. The WeBWorK "system" is fine under /usr/local as it is static data which is not going to change during the life of the system, does not need to be backed up frequently, and can be located on a read-only storage medium (after initial configuration, of course). However, the "courses" data should really be located under /var/local, as it is variable data and should be on storage that is mounted read-write and is backed up regularly. If you want to set up WeBWorK this way, follow the instructions below.

As root, create a webwork directory in /var/local and set privileges on it:

# mkdir /var/local/webwork
# chown <username> /var/local/webwork
# chgrp wwadmin /var/local/webwork

As a regular user, move the courses directory into your new webwork directory:

> mv /usr/local/webwork/courses /var/local/webwork

Now, a slight modification to the structure of the WeBWorK system structure must be made. The directory /usr/local/webwork/system/courses contains symlinks to each course directory, for use by system scripts. These symlinks must be created manually for each course. Instead of this, we would like this directory to point to the actual courses directory. Therefore, as a normal user, run:

> rm -r /usr/local/webwork/system/courses
> ln -s /var/local/webwork/courses /usr/local/webwork/system

Also, it is a good idea to "crosslink" the courses and system directory so that we can easily move between them without typing out the absolute paths:

> ln -s /var/local/webwork/courses /usr/local/webwork
> ln -s /usr/local/webwork/system /var/local/webwork

Some WeBWorK documentation will instruct you to maintain course symlinks in /usr/local/webwork/system/courses. After you make these modifications, you no longer need to do this.

Step 9: Separating out temporary WeBWorK data

This is an advanced step that major users may want to consider.

If you are using WeBWorK with a substantial number of students (say a hundred or more) you probably should use the following method of setting up tmp directories. This is what we do at Rochester. The main point is that WeBWorK creates a lot of small temporary (and not so temporary) files and these can use up a lot of inodes (i.e. disk resources) and also slow up backups.

As an aside --- this is not a system setup issue--- every week or two it's a good idea to go to the prof page, then Housekeeping utilities (item 14), and click on remove tmp files and compress the gdbm database. This removes all non latex2html tmp files. It will also substancially reduce the size of the webwork database.

In a standard setup under the html directory for a course you will find a tmp directory. Under that are various directories. Everything under tmp will be recreated if deleted. Since latex2html (l2h), which is used for typeset output, is so slow, we cache the l2h images and these are saved under html/tmp/l2h/ . These l2h files should be kept at least until students no longer are looking at the problems (we keep them all semester). If you remove them, it slows things down since these images have to be recreated. The remove tmp files button referred to above does not delete these files but does delete all other tmp files.

Where the tmp directory for a course is located is determined by the webworkCourse.ph file. What we do at Rochester is create a new file system for all tmp directories from all courses and put it under the $DOCUMENT_ROOT directory. So we have

$DOCUMENT_ROOT/tmp/

the tmp directory (file system) is set up with (this is system dependent)

newfs -i 512 tmp

so there are plenty of inodes (the -i switch specifies number of bytes per inode). Also this file system is never backed up. I think by default most OS's, e.g. Solaris, use many fewer inodes.

Under tmp we have a directory for each course, e.g.

$DOCUMENT_ROOT/tmp/mth142/

We change the webworkCourse.ph file for each course as follows:

FIRST CHANGE

#  This is the temp directory used by downloadPS, etc

#$courseTempDirectory = "${classDirectory}html/tmp/";
$courseTempDirectory = "$DOCUMENT_ROOT/tmp/mth142/";

SECOND CHANGE

#  This is the URL of the course tmp directory.  This is for temporary storage of
#  html files, images, etc that have to accessible to the webserver.  This directory
#  contains the subdirectories l2h, gif, eps, and html (not the ${classDirectory}html
#  directory). All these subdirectories and their files will be recreated if deleted
#  (althought recreating l2h files is time consuminmg).  The location of this directory
#  may be changed fast disk which is not backed up.

#$courseTempURL = "${htmlURL}tmp/";
$courseTempURL = "/tmp/mth142/";

Note that if you do not set up the tmp as a subdirectory of $DOCUMENT_ROOT/ you will have to setup a link in the $DOCUMENT_ROOT/ pointing to the tmp directory. If you name the link tmp, you can use $courseTempURL as above.

Also you should note that the access and timing logs can get huge. These are in webwork/system/logs/

By default, these logs are not kept. You can turn on the access log by changing $logAccessData = 0; in the Global.pm . The timing log keeps track of how fast the server is responding. You can keep track of individual scripts. The most important one is processProblem8.pl (edit around line 40 $main::logTimingData = 1;).

Step 10: Obtaining Additional Support

Online support is available at: <a href="http://webwork.math.rochester.edu/docs/">http://webwork.math.rochester.edu /docs/

<| Post or View Comments |>