Forum archive 2000-2006

Arnold K. Pizer - Setting up a WeBWorK course

Arnold K. Pizer - Setting up a WeBWorK course

by Arnold Pizer -
Number of replies: 0
inactiveTopicSetting up a WeBWorK course topic started 5/3/2000; 9:50:59 PM
last post 5/3/2000; 9:50:59 PM
userArnold K. Pizer - Setting up a WeBWorK course  blueArrow
5/3/2000; 9:50:59 PM (reads: 2578, responses: 0)

Setting up a WeBWorK course

You can set up a "working" or a "demo" version of a course. A "demo" version should only be used as a sample course, never for an actual course. In a "demo" version all the system type files specific to the course (e.g. are world readable and many files are world writable. Other than that, "working" or "demo" versions function the same.


The "you" in these instructions refers to the person setting up the course, usually a member of the wwadmin group that was established when the WeBWorK system was setup.



First, decide what will be your base course directory (mth140a in our example), i.e. where you want course specific files. The recommended place to put base course directories is under the courses subdirectory of the main webwork directory. In our setup this means /www/webwork/courses/mth140a and I will use this as an example. In a chroot environment I would use /www/webwork-root/webwork/courses/mth140a as my base course directory.


Decide what you will use as your course URL. Since we have a separate WeBWorK www server, I use and will use this as an example. If we didn't have a separate server, I would use Remember this course URL (at least the /mth140a/ part) as it will be needed by the installation process below.


Have your system administrator (root) set up your base course directory, e.g. mth140a. This directory is set up by entering
mkdir mth140a
in the /www/webwork/courses/ directory. You need to be the owner of this directory so make sure your system administrator (root) gives you ownership.



Have your system administrator (root) set up a link to your base course directory from the courses subdirectory of system. This link is setup by runnng (in the /www/webwork/system/courses/ directory)
ln -s ../../courses/mth140a mth140a
This link name (mth140a) is used a lot and we refer to it as the classID. Remember this classID as it will be needed by the installation process below.

Note that the courses subdirectory of system is distinct from the courses subdirectory of webwork. The courses subdirectory of system just contains links. Using this method, it is easy to upgrade the system without changing actual courses. Also, it is possible to have in addition to the standard system an "experimental WeBWorK system" and to be able to run a course under either system.


You can skip step 5 for a "demo" version. Have your system administrator (root) set up a special group (e.g. mth140agroup) containing the user name under which the web server runs, your user name, and the user names of anyone else (e.g. other professors and TA's) who will creating and editing WeBWorK problems for your course. In my setup, the classID and the group name are different. (one is mth140a and the other is mth140agroup). This is convenient, but not necessary. If you don't know name under which the web server runs, you might grep the output of the ps command for HTTP. Depending on the flavor of unix you are using, try running one of the following commands:
    ps -aux | grep httpd  OR
ps -ef | grep httpd

The web server will need to be restarted for the changes to take effect. You may also need to log out and log back in again for the same reason. Finally, if your server runs in a chroot environment, be sure to add this group to the chrooted /etc/group file as well. Remember this group as it will be needed by the installation process below.

Note: to see what groups you are in, run the command id and to see what groups the web server is in run the command id wwserver where you should replace wwserver by the user name of the web server.


In your base course directory (e.g. .../mth140a), set up needed directories and files. The easiest way is to copy everything from demoCourse:


    cd /www/webwork/courses/mth140a
cp -r /www/webwork/courses/demoCourse/* .

or even better,


    cd /www/webwork/courses/demoCourse
tar cf - . | (cd /www/webwork/courses/mth140a ; tar xvf -)

The use of tar is preferred, because cp does not always preserve all file attributes, e.g., it may not understand symbolic links.


Don't worry if you are denied permission to copy the keys file. You don't need it. You will have extra *.def (and associated subdirectories) and *.lst files in the templates directory. Keep these arround for a while to use as samples.



Your system administrator (root) will have to set an additional link (or links) depending on what you choose as the URL of the course and how your webserver is set up. The only things that are the same for all setups are (1) you have to start from under the webserver's document root (often a directory called htdocs or html) and (2) you have to end up in the html subdirectory of the base course directory. For example, my setup is as follows. Our webserver ( has /www/htdocs/ as its document root. In that directory there is a link mth140a -> ../webwork/courses/mth140a/html. This link is setup by running (in the htdocs/ directory)
ln -s ../webwork/courses/mth140a/html mth140a


Thus the URL for my course is Note that the URL ends up pointing to the html subdirectory of the base course directory.


This can be very confusing and is also highly dependent on how your web server is set up. You will probably need the assistance of your system administrator to set things up correctly even if you have permission to make such changes.


cd to the base course directory and run the course setup script:


    cd /www/webwork/courses/mth140a

For this you will need to enter the course URL, the cgi WeBWorK URL, the classID, and, for a "working" version, the group.


  • The course URL ( is the one decided upon above. It is sufficient to enter just /mth140a/ but if you do this, don't forget to enter the initial "/".


  • The cgi WeBWorK URL points to the url of the main WeBWorK cgi subdirectory. It is listed in the file as $cgiWebworkURL . The file is contained in the system subdirectory of the main WeBWorK directory /www/webwork/. If there is an initial "/" such as in /cgi-bin/webwork/system, don't forget to enter it.


  • The classID is the name of the link (e.g. mth140a) which your system administrator set up (see step 4 above) in the /www/webwork/system/courses/ directory.


  • The group is the special group (e.g. mth140agroup) containing the webserver, your loginID, and the loginID's of anyone else who will creating and editing WeBWorK problems for your course which your system administrator set up (see step 5 above). You don't need a special group for a "demo" version.


  • Finally, answer Y to all questions to allow to create needed directories and files and to set default permissions.



If you make a mistake, you can always run again.


At this point you should have a working setup (but see the NOTE below) if you answered Y to every question asked by To test it, connect to your url (e.g. and login as practice1 with password any non blank characters (e.g. practice1 ). Try some problems to make sure everything is working. Login as apizer with password 111-11-1111 and you will have professor privileges.


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 files and directories. To do this, remove everything from mth140a/html/tmp/
    cd /www/webwork/courses/mth140a/html/tmp
rm -rf *
Finally for a totally new course remove all the scoring files (if any) from mth140a/scoring/
    cd /www/webwork/courses/mth140a/scoring
rm *
In the mth140a/templates/ directory there are a number of header files, set definition files, problem templates, emails, etc that you may or may not want to keep as samples. We do recommend that you keep these files around for awhile. In particular the *.tex files are used to tex problems and probably should not be changed. The and are default header files which will be used unless the set definition file (e.g. set2.def) specifically calls for different header files.

Now go back to mth140a and cd to html. Edit the index.html file (you don't have to edit this but you probably will want to). This is the first page your students will see. You should enter your course name and other information here. E.g. you may want to add name(s) of professors, a link to the course syllabus, etc. You can connect to courses at to see the type of things some people put in their index.html file. The generic index.html file created by is very simple, but is usable.


You can skip step 12 for a "demo" version. Now we need to change permissions on templates/ so that all new files created in templates will have mth140agroup as their default group. We do this as follows. First go back to mth140a and then:


chmod g+xs templates

If you do not use chmod g+xs as above to set the group setID, then when you create new directories and files the group ownership will not be automatically set for you, and you will have to be very careful to set the group and/or permissions properly so that they are accessible from the webserver.


If you have not changed file permissions using, look at help with permissions for some help on setting permissions. We strongly recommend that you let set the permissions for you as setting permissions correctly is very trickly. Actuallly the "help with permissions" document may be out of date. A better source of information is to look at the code in

If a professor (e.g. jsmith) is in the mth140agroup, he or she should have sufficient privileges to do everything necessary to administer the course. However, if you want, you can have your system administrator (root) change the ownership of all files and directories to this professor. Before you do this, remove the keys file. The keys file has to be owned by the web server (e.g. wwserver) and it will always be recreated by the webserver if it doesn't exist. To change ownership, have your system administrator (root) run:


    cd /www/webwork/courses
rm mth140a/DATA/.auth/keys
chown -R jsmith mth140a



Now you will definitely want to continue reading A DAY IN THE LIFE OF A WEBWORK PROFESSOR for further information.


<| Post or View Comments |>