Forum archive 2000-2006

Amanda Danforth - Setting up a Webwork Course

Amanda Danforth - Setting up a Webwork Course

by Arnold Pizer -
Number of replies: 0
inactiveTopicSetting up a Webwork Course topic started 7/29/2002; 2:17:24 AM
last post 7/29/2002; 2:17:24 AM
userAmanda Danforth - Setting up a Webwork Course  blueArrow
7/29/2002; 2:17:24 AM (reads: 2819, 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 (mth141 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 /ww/webwork/courses/mth141 and I will use this as an example. In a chroot environment I would use /ww/webwork-root/webwork/courses/mth141 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 /mth141/ part) as it will be needed by the installation process below.


Have your system administrator (root) set up your base course directory, e.g. mth141. This directory is set up by entering
mkdir mth141
in the /ww/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 /ww/webwork/system/courses/ directory)
ln -s ../../courses/mth141 mth141
This link name (mth141) 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. We do this so that it is easy to upgrade the system without changing actual courses. Or, if we have an addition system (e.g."experimental WeBWorK system") we can 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. mth141group) 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 be creating and editing WeBWorK problems for your course. 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 appropriate user name of the web server.

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


    cd /ww/webwork/courses/mth141
cp -r /ww/webwork/courses/blankCourse/* .

or even better,


    cd /ww/webwork/courses/blankCourse
tar cf - . | (cd /ww/webwork/courses/mth141 ; 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 /ww/htdocs/ as its document root. In that directory there is a link mth141 -> ../webwork/courses/mth141/html. This link is setup by running (in the htdocs/ directory)
ln -s ../webwork/courses/mth141/html mth141


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.


Now you need to run the script 

If you have set /ww/webwork/system/scripts in your path, then all you need to do is run the command

Otherwise, if /ww/webwork/system/scripts is not in your path, then you need to type the whole command


For this script 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 /mth141/ 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 /ww/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. mth141) which your system administrator set up (see step 4 above) in the /ww/webwork/system/courses/ directory.


  • The group is the special group (e.g. mth141group) 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 mth141/html/tmp/
    cd /ww/webwork/courses/mth141/html/tmp
rm -rf *
Finally for a totally new course remove all the scoring files (if any) from mth141/scoring/
    cd /ww/webwork/courses/mth141/scoring
rm *
In the mth141/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 you have to rebuild the databases so that you can log in from the web. Run
-- Edit theCourse.lst as necessary (probably just adding the professor; it's
best to add students through the web)

-- In /ww/webwork/courses/theCourse: theCourse
--Type y

-- theCourse loginName

Now the database has been built. You can add additional students from the web -- it's easier. Now go back to mth141 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 mth141group as their default group. We do this as follows. First go back to mth141 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 mth141group, 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 /ww/webwork/courses
rm mth141/DATA/.auth/keys
chown -R jsmith mth141


This completes the setup for your course. However, it is suggusted that you make two copies of your course, one the actual working course that the students use (mth141) and one called the "private" course, for example mth141priv. The private course is used mainly for your benefit so that you can try out new problems, or write up an exam without interfering with the students.

The setup for the private course is the same as your "public" course except for the following differences:

  • The private course URL should be something hidden so that the course is not easily found by students. The public URL for the course mth141 is We make the URL for the private course mth141priv

  • The classlist for the private course should only include those people who are working on new problems or are doing any kind of editing. Thus, don't include any practice users. See Classlist Information for more details on classlists.

  • You should be able to destroy and rebuild problem sets in your private course. This is something that is generally not done in public courses. You use this feature when you change set definition files after a problem set has been built. Thus, in your file, make sure that $allowDestroyRebuildProbSets = 1 See "Course Enviornment" for more information

Now you will definitely want to continue reading Creating and Managing a WeBWorK Course for further information regarding classlist setup, and course enviornment setup. This will complete the WeBWorK Course setup and you can begin to use your course.


<| Post or View Comments |>