|Installing WeBWorK on a Linux System||topic started 7/24/2003; 3:34:54 PM
last post 7/24/2003; 3:34:54 PM
|Arnold K. Pizer - Installing WeBWorK on a Linux System
7/24/2003; 3:34:54 PM (reads: 624, responses: 0)
Installing WeBWorK on a Linux System
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 <email@example.com>; has posted a makefile
which will install a separate configured copy of all required packages on your system.
Connect to <a
select the CVS Root
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
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
> perl -V | grep libs=
In this case, libm, libc, and libcrypt are compiled into perl.
> ldd `which perl`
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
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.
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
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
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:
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
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:
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
$PK_GENERATION = 1
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 <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:
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
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 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
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
# useradd wwserver
Then, in the apache configuration file
Change them so that they list
There are two ways that the webserver can be given access to WeBWorK files.
The first is to add an explicit
In either case, your document root must have
The important line is
If you chose to use a
ScriptAlias /cgi-bin/webwork/system/ "/usr/local/webwork/system/cgi/"
Make sure that these lines go before any existing
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:
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
This results in the creation of a webwork_VERSION_SUBVERSION-MONTH-DAY-YEAR
directory which contains several readme files and the
cd webwork_VERSION_SUBVERSION-MONTH-DAY-YEARNext we must copy the
# 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
# groupadd wwadmin
You can add any number of users with the second command, replacing
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
# mkdir $DOCUMENT_ROOT/webwork
If you chose not to add a
# mkdir $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
> 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
> chgrp -R wwadmin /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
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/
In order to use logging, you need to give the web server write access to the
# chgrp -R wwserver /usr/local/webwork/system/logs
Check that the path to the various Netpbm utilities are correct in the two
There are some user-definable settings that you should customize in the file
Global.pm. This file is located at:
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.
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
Set the permissions on the new directory.
> chgrp -R wwadmin 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:
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
To test your installation of WeBWorK, you must now create a course. The base
you will use to create this course is located in
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,
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
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
> cd /usr/local/webwork/courses
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
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)
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
> 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
> 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
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:
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:
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
$Global::feedbackAddressIn general you should look through
Step 8: Separating Static and Variable WeBWorK data
Right now, all WeBWorK files are located under
As root, create a
# mkdir /var/local/webwork
As a regular user, move the courses directory into your new
> 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
> rm -r /usr/local/webwork/system/courses
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
Some WeBWorK documentation will instruct you to maintain course symlinks in
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
the tmp directory (file system) is set up with (this is system dependent)
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.
We change the webworkCourse.ph file for each course as follows:
# This is the temp directory used by downloadPS, etc
# This is the URL of the course tmp directory. This is for temporary storage of
Note that if you do not set up the
Also you should note that the access and timing logs can get huge. These are
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/