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:
-
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.
-
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.
-
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.
-
Change
$webmaster = 'webmaster@math.rochester.edu'; so that it is correct
for your system.
-
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.
-
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.
-
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.
-
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 |> |