For WeBWorK version 1.8
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 8.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 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.
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 http://www.gnu.org/software/gdbm/.
Please refer to the perl source code distribution site at 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.gzand then read the README file.
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.
You now have to install additional perl modules needed for WeBWorK. These are HTML::Parser, Net::SMTP, MIME::Base64, and GD. You can use CPAN to install the first three.
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
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, and MIME::Base64 (and GD, see below) were installed successfully. If you do not run these tests now, at least remember them in case you get error messages concerning modules later.
You also have to install the GD module. Currently (Fall 2002) if you use CPAN to install GD, it will install the 2.01 version of GD.pm which requires the beta 2.0.1 version of gd. Unfortunately there is a known bug in gd 2.0.1 which prevents it from drawing horizontal dashed lines. We recommend using gd 1.8.4 and GD 1.33 or 1.29. gd is probably on your system. For GD, go to http://stein.cshl.org/WWW/software/GD/.
As a normal user, download the tar/gzip archive for version 1.33 (or 1.29) and untar it:
> tar -xzf GD.pm.tar.gzthen cd to the
GD-1.33
subdirectory and follow the installation instructions
in the README file. Usually this means running the commands:
> perl Makefile.PL (select JPEG but not FreeType or XPM support for WeBWorK) > make
Then, as root, install it.
# make installIf you have difficulty, read the README file and also look at the special instructions Installing WeBWorK on a Red Hat Linux 8.0 System which explain the changes necessary to install GD on that operating system.
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:
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 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
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 http://hutchinson.belmont.ma.us/tth/ . If you can, download a precompiled binary. Otherwise, download the source and the following other packages:
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 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 probably use it in place of LaTeX2HTML in the future. Currently it is still in the experimental stage. For information on obtaining and installing dvipng visit John Jones's site http://hobbes.la.asu.edu/webwork-stuff .
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.
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-YEARNext we must copy the
webwork
directory to /usr/local
. As root, run:
# 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.
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. ##################### # 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. $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 almost as fast as tth but dvipng is still in a beta version. This is our recommended choice.)
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.
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 > 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.
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 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. 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 Enter Build Problem Set Page which should be the only option you see. 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.
Next, we can check onscreen display. Select a problem set and click Do_problem_set. View several problems from the set on all three display modes: text, raw TeX source code, formatted- text, TTH 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.
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'}In general you should look through
Global.pm
(located in
/usr/local/webwork/system/lib/
) and webworkCourse.ph
(located in
/usr/local/webwork/courses/course_name/
). The variables defined in
Global.pm
set defaults and
parameters for the whole WeBWorK system. The variables defined in
webworkCourse.ph
set defaults and
parameters for an individual course. The defaults given in Global.pm
can
be over ridden for an individual course by redefining
them in webworkCourse.ph
.
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.
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;).
Online support is available at: http://webwork.math.rochester.edu /docs/