# Difference between revisions of "Upgrading WeBWorK"

These instructions cover upgrading the WeBWorK system (webwork2, pg, and problem libraries), and are especially designed to cover the case when you have existing WeBWorK courses.

They are conservative in the sense that they save your old WeBWorK system in such a way that you can quickly switch out your new system and switch back in your old system if need be.

## Assummed Set Up

For convenience I will assume you that your WeBWorK system has been set up using recommended directory locations, etc. as in e.g. Installation Manual for 2.4 on Ubuntu 10.04. Specifically I'll assume

• the top level webwork2, pg, and libraries directories are
• /opt/webwork/webwork2
• /opt/webwork/pg
• /opt/webwork/libraries
• the files and directories are owned by the WeBWorK administrator wwadmin
• files and directories that the webserver (Apache2) needs write access to are in the group wwdata

## Notation

First some short comments on notation we will be using. We will use <key> to indicate that you should press a specific key (e.g. <Enter>, <Tab>, <F12>, etc.). Sometimes we will also use e.g. <root password> to indicate you have to enter the root password.

^ will indicate the <Ctrl> key so e.g. ^X is really shorthand for <Ctrl> <X>, i.e. press the Ctrl key and hit the X key.

We will use # to indicate that the command is to be run as root e.g.

# perl -MCPAN -e shell


and $to indicate that the command is to be run as a normal user e.g. $ cp .bashrc .bashrc.bak1


We will use Subversion to download WeBWorK. Note that the following are rather long commands; it is much easier to copy (^C) them from this document and paste (<Shift> <Ctrl> <V>) them in a terminal window.

$cd$ cd downloads

$svn co http://svn.webwork.maa.org/system/branches/rel-2-4-patches/webwork2$ svn co http://svn.webwork.maa.org/system/branches/rel-2-4-patches/pg



## Installing WeBWorK

Note the the instructions below assume you are installing WeBWorK from scratch. If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see Upgrading WeBWorK.

### Move the System into the Required Directories

As root create a webwork directory under /opt, change the ownership of the webwork directory to wwwadmin and move directories there.

$sudo mkdir /opt/webwork <wwadmin password>$ sudo chown wwadmin:wwadmin /opt/webwork
$mv webwork2 /opt/webwork/$ mv pg /opt/webwork/


Now create the courses and libraries directories under webwork and copy and move content there being careful not to copy the .svn directories

$mkdir /opt/webwork/courses$ mkdir /opt/webwork/libraries
$mv NationalProblemLibrary /opt/webwork/libraries/$ cd /opt/webwork/webwork2/courses.dist
$cp *.lst /opt/webwork/courses/$ rsync -a --exclude '.svn' modelCourse /opt/webwork/courses/


### Setting Permissions

The PG installation directory and files should be owned by wwadmin and not writable by other users:

$cd /opt/webwork/pg$ chmod -R u+rwX,go+rX .


Most WeBWorK directories and files should also be owned by wwadmin and not writable by other users:

$cd /opt/webwork/webwork2$ chmod -R u+rwX,go+rX .


Certain data directories need to be writable by the web server. These are DATA, courses, htdocs/tmp, logs, and tmp. It is convenient to give WeBWorK administrators access to these directories as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on. We will create a new group called wwdata, containing both the WeBWorK administrators and the web server.

1. Select System, Administration and then Users and Groups
2. Click on Manage Groups
3. Click Add
4. Enter <wwadmin password> and click Authenticate
5. For Group name enter wwdata
6. For Group ID accept the default which is probably 1001
7. Under Group Members check wwadmin and click OK
8. Click Close

If there are other users who will also be administering WeBWorK files, now is a good time to add them. And remember to add them to the wwdata group as above. When finished

1. Click Close again

Because system users are not shown by default, we can not simply use the Group Manager to add the Apache2 webserver (which runs as www-data) to the wwdata group so we will do this by hand as root.

$su Password: <root password> # cd /etc # cp group group.bak1 # gedit group  1. In the gedit window scroll to the last line. 2. It should look like wwdata:x:1001:<wwadmin userid> 3. Append to this line ,www-data 4. Then Save and Quit You can check that this succeeded in a terminal window by entering # exit$ id wwadmin


and then you should see wwdata listed under groups. Also

$id www-data  should show wwdata listed under groups. Now we make the WeBWorK directories that need to be writable by the web server have wwdata as their group. The following are rather long commands; you might want to copy them and paste them into your terminal window rather than typing them. $ su
# cd /opt/webwork/webwork2/
# chgrp -R wwdata DATA ../courses htdocs/tmp logs tmp
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a ! $$-name .svn -prune$$ -exec chmod g+s {} \;
# exit
$ ## Configuring the Shell To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment. Add the WeBWorK bin directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Goto your home directory and backup your .bashrc file $ cd
$cp .bashrc .bashrc.bak1  Now edit .bashrc $ gedit .bashrc


After the last line add the three lines:

export PATH=$PATH:/opt/webwork/webwork2/bin export WEBWORK_ROOT=/opt/webwork/webwork2 export PG_ROOT=/opt/webwork/pg  Then save the file and Quit. Close your Terminal Window and open a new one so the above changes take effect. You can check that they have by $ echo $PATH$ echo $WEBWORK_ROOT$ echo $PG_ROOT  ## Checking Module Dependancies WeBWorK includes a script called check_modules.pl that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules. $ check_modules.pl apache2


Scroll up and look through the listing. It should find everything except tth which is a deprecated display mode. If something is missing (flagged by **), look back through these instructions and/or look at Installation Manual for 2.4 to find where it should have been installed and install it. Note you may have to search in Installation Manual for 2.4 to find out what package it is contained in.

## Configuring WeBWorK

### Making Copies of the Distribution Configuration Files

Before configuring the system, you must make local copies of the global.conf and database.conf configuration files, located in /opt/webwork/webwork2/conf/ .

$cd /opt/webwork/webwork2/conf$ cp global.conf.dist global.conf
$cp database.conf.dist database.conf  ### Global Configuration Most WeBWorK configuration is done in the file /opt/webwork2/conf/global.conf. This file provides system-wide configuration settings, and defaults for course settings. Any setting in this file can be overridden in the course.conf file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in global.conf) in the course.conf file. There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. Now edit global.conf $ cd /opt/webwork/webwork2/conf
$gedit global.conf  WeBWorK uses the DateTime module. DateTime is supposed to be able to determine the local timezone itself without you having to enter it but this often fails so it is best to just set it here. For is a list of timezones recognized by DateTime go to http://search.cpan.org/dist/DateTime-TimeZone/ . These timezones are more refined than standard timezone usage in that they include switches to daylight savings time (e.g. some parts of a time zone may make the switch and others may not). For example if your server is in the eastern US, on the list you will see DateTime::TimeZone::America::New_York and you should enter $siteDefaults{timezone} = "America/New_York"; which is the default.

1. Search for $siteDefaults{timezone} and enter your local timezone if it is not correct. Since we have installed MathJax we need to add it as a possible display mode. 1. Search for render TeX math expressions on the client side using MathJax and uncomment whole line so it becomes  "MathJax", # render TeX math expressions on the client side using MathJax --- we strongly recommend people install and use MathJax  We need to set a password that WeBWorK uses when it communicates with the MySQL database. Note that this is not the same as the <mysql root password> which is the password the MySQL root user uses. 1. Search for $database_password = ""; and replace this by
$database_password = "database_password"; where of course you should replace 'database_password' with your own password. Remember this password as we will need it below. WeBWorK sends mail in three instances. The PG system sends mail to report answers to questionnaires and free-response problems. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors. To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use localhost. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configue one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the From address on the mail message). Edit the lines $mail{smtpServer}            = 'mail.yourschool.edu';
$mail{smtpSender} = 'webwork@yourserver.yourschool.edu';  entering the appropriate information. If you want WeBWorK questionnaires or similar things from different courses to be mailed to a central person or persons (e.g. the WeBWorK administrator), edit the lines $mail{allowedRecipients}     = [
#'prof1@yourserver.yourdomain.edu',
#'prof2@yourserver.yourdomain.edu',
];


appropriately removing the # and using the professor(s) actual email address(es). In order to have professors from individual courses receive such email, this should be set in course.conf (which you find in the course directory) to the addresses of professors of each course. Note that the settings in course.conf override the settings in global.conf, so if in addition you want e.g. the WeBWorK administrators to receive copies, you have to add them as well.

Then save the file and Quit.

WeBWorK uses a single database, called webwork, for all courses. We will create the webwork database now.

To do this do the following (before you just copy, paste and hit <Enter> notice that you have to replace database_password with the password you set when editing global.conf above):

$mysql -u root -p mysql Enter password: <mysql root password> mysql> CREATE DATABASE webwork; mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO webworkWrite@localhost IDENTIFIED BY 'database_password'; mysql> exit Bye$


where as we said replace database_password with the password you set when editing global.conf above.

The database needs needs to be initialized. We do this now with the command

$tar vfxz jsMath-fonts.tar.gz  This will unpack the archive. Since there are 20,000 tiny files, it can take a little while, so the v option is used to show you the names as they are unpacked so that you know the command is actually doing something. Once the images are unpacked, jsMath's image mode fallback (the default fallback method) will work properly. ### Install MathJax General information on MathJax can be found at http://www.mathjax.org/ and general installation instructions are at http://www.mathjax.org/resources/docs/?installation.html . First we download MathJax. We generally recommend using the trunk version which is the latest development version. If you prefer to use the most stable version (that may not include all the latest patches and features), check the documentation above and change the svn command below accordingly. $ cd
$cd downloads$ svn co http://mathjax.svn.sourceforge.net/svnroot/mathjax/trunk/mathjax mathjax
$mv mathjax /opt/webwork/webwork2/htdocs/$ cd /opt/webwork/webwork2/htdocs/mathjax
$unzip fonts.zip  ## Configuring Apache WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named webwork.apache2-config.dist and located in the conf directory. First, copy the file to webwork.apache2-config: $ cd /opt/webwork/webwork2/conf
$cp webwork.apache2-config.dist webwork.apache2-config  and now link it into your Apache configuration process $ su
# cd /etc/apache2/conf.d
# ln -s /opt/webwork/webwork2/conf/webwork.apache2-config webwork.conf


Next we will make a few changes to Apache's default configuration. First we backup the configuration file

# cd /etc/apache2/
# cp apache2.conf apache2.conf.bak1
# gedit apache2.conf


Search for the line

Timeout 300


and replace it by

Timeout 1200


Next seach for the lines

    MaxClients          150
MaxRequestsPerChild   0


Which occur under <IfModule mpm_prefork_module> and replace them by

# For WeBWorK a rough rule of thumb is 20 MaxClients per 1 GB of memory
MaxClients           20
MaxRequestsPerChild  100


where you should set MaxClients depending on the amount of memory your server has using the above rule of thumb.

Then save the file and quit.

Finally we copy WeBWorK's icon file favicon.ico to Apache's www directory.

# cp /opt/webwork/webwork2/htdocs/favicon.ico /var/www


Now restart Apache

# apache2ctl graceful
# exit
$ ## Test your configuration 1. Test the /webwork2 location by visiting http://yourserver.yourschool.edu/webwork2. You should see the WeBWorK home page with no courses listed. Actually the directory /opt/webwork/courses/ does contain the modelCourse but the modelCourse is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason /opt/webwork/courses/modelCourse/ contains a file named hide_directory and so the modelCourse is not visible. 2. Test the /webwork2_files location by visiting http://yourserver.yourschool.edu/webwork2_files. You should see the "WeBWorK Placeholder Page". 3. You cannot test the /webwork2_course_files location until you have created a course. ## If Something is Wrong If something is wrong one of the first things to check is that the config files have been edited correctly (e.g. one time a wrapped line in global.conf caused me problems, another time it was a missing single quote). A quick way to check this is to do a diff between the edited and distributed versions and check that diff reports the changes you made and only those. # exit$
$cd /etc/apache2/$ diff apache2.conf apache2.conf.bak1
$cd /opt/webwork/webwork2/conf/$ diff global.conf global.conf.dist
$diff database.conf database.conf.dist$ diff webwork.apache2-config webwork.apache2-config.dist


If something is wrong and you fix it, you will have to restart Apache for the changes to take effect

$su <root password> # apache2ctl graceful # exit$


Course Administration gives information about creating courses. Here we will give explicit instructions for doing this.

$newgrp wwdata$ umask 2
$cd /opt/webwork/courses$ /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin
$exit  Now goto http://yourserver.yourschool.edu/webwork2 and should see the WeBWorK home page with Course Adninistration listed at the top. Click on it and login with Username admin and Password admin . This first thing you should do is register your new WeBWorK installation. It's quick and easy, just click on Register. The next thing you should do is click on Password/Email and change admin 's password to something more secure than admin . Unless you choose oherwise, users with professor privilges in the admin course (i.e. WeBWorK administrators) will automatically be added to new courses with professor privilges and the same password as in the admin course. Initially the only such user is admin (hopefully you are not confused by the fact that the course admin has a user named admin). It's usually convenient make yourself a WeBWorK administrator. To do this (assuming you are logged in as admin to the admin course at http://yourserver.yourschool.edu/webwork2/admin ) 1. Click on Classlist Editor in the left panel 2. Check Add 1 student(s) and click Take Action! 3. Enter the appropiate information (you can leave the last three items blank) and click Add Students 4. Click on Classlist Editor in the left panel again 1. When you enter a new student, by default their Student ID is used as their password. We'll change this now. 2. Select yourself with a check mark and then check Give new password to Selected users or just check Give new password to All users (as a safely mechanism you can not change the password for the user you are logged in as, currently admin, this way) and then click Take Action! 3. Enter the password, check Save changes and then click Take Action! 4. Finally give yourself professor privilges by selecting yourself with a check mark, checking Edit Selected users and then clicking Take Action! (or by just clicking on the "pencil" next to your login name which is a much faster way to edit classlist data for a single user) 5. Now at the far right change Permission Level from student to professor 6. Check Save changes and then click Take Action! At some point you will probably want to hide the admin course so that it is not listed on the WeBWorK home page. As we noted above the modelCourse, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The modelCourse is very useful as a model (hence its name) for setting up other courses. The admin course is used for administering WeBWorK and even though regular users can not log into it (you did change the admin password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes. To hide a course place a file named hide_directory in the course directory and it will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the admin course using the URL http://yourserver.yourschool.edu/webwork2/admin but you will not see a link for it on the WeBWorK home page http://yourserver.yourschool.edu/webwork2 . Let's hide the admin course. $ cp /opt/webwork/courses/modelCourse/hide_directory /opt/webwork/courses/admin


Now goto http://yourserver.yourschool.edu/webwork2 and no course will be listed.

## Starting and Stopping Apache, MySQL and the GNOME desktop GUI

If you make changes to the system, you will have to restart apache2 before the changes take effect. On rare occasions you may need to restart MySQL.

### Starting and Stopping Apache

You have to run these commands as root.

To start or restart (i.e. stop and then start) the apache2 webserver run the command

$sudo apache2ctl graceful password:<wwadmin password>  You can also start apache2 by $ sudo apache2ctl start


and restart it with

$sudo apache2ctl restart password:<wwadmin password>  restart is less graceful but more powerful than graceful. Sometimes graceful fails to kill all apache2 child processes. To stop the Apache webserver run the command $ sudo apache2ctl stop


You can also start or stop apache2 by using the init.d script apache2. Run

$sudo /etc/init.d/apache2 password:<wwadmin password>  and you will get a list of allowed commands (start, stop, restart, etc). ### Starting and Stopping MySQL You have to run these commands as root. To start the MySQL server run the command $ sudo /etc/init.d/mysql start


To stop the MySQL server run the command

$sudo /etc/init.d/mysql stop password: <wwadmin password>  To restart the MySQL server run the command $ sudo /etc/init.d/mysql restart


### Starting and stopping the GNOME desktop GUI

The GNOME desktop is automatically started when the system boots.

To stop GNOME so that you only have a standard terminal window run the following in a standard terminal window

$sudo /etc/init.d/gdm stop password: <wwadmin password>  If you stopped GNOME and want to restart it run the following in a standard terminal window $ sudo /etc/init.d/gdm start


## Install the WeBWorK Problem Libraries

Before we create a real course we will install the WeBWorK Problem Libraries.

### Install the National Problem Library

The National Problem Library consists of both WeBWorK problems and methods for searching and selecting problems. Also it contains as sub libraries many of the other standard libraries. We have to tell WeBWork where to find it.

Edit global.conf.

$cd /opt/webwork/webwork2/conf$ gedit global.conf


Search for problemLibrary and replace $problemLibrary{root} = ""; by $problemLibrary{root} = "/opt/webwork/libraries/NationalProblemLibrary";

Then save the file and quit.

Run the NPL-update script making sure you are in the /opt/webwork/libraries/NationalProblemLibrary directory. This directory contains the files loadDB2 and create_tables2.sql.

$cd /opt/webwork/libraries/NationalProblemLibrary$ NPL-update


This has to convert a lot of data for over 20,000 problems so please be patient; it can take a long time.

If at some time in the future you want to upgrade the Problem Library, the process is simpler. Optionally remove the previous copy of the library, unpack the new copy in the same place, and run NPL-update.

Finally we put a link to the National Problem Library in the modelCourse so that when we create courses copying templates from the modelCourse, the NPL will be available.

$cd /opt/webwork/courses/modelCourse/templates/$ ln -s /opt/webwork/libraries/NationalProblemLibrary Library


### Set up the Rochester and Union Libraries

This step is optional. It creates buttons in the Library Browser which give direct links to the Rochester and Union libraries. If you don't do this, you can find these libraries and others under the NPL Directory button.

First we need to edit global.conf one last time

$cd /opt/webwork/webwork2/conf$ gedit global.conf


Search for courseFiles{problibs} and scroll down several lines to the lines

#      rochesterLibrary => "Rochester",
# 	 unionLibrary     => "Union",


Uncomment these lines (i.e. remove the #) so they become

      rochesterLibrary => "Rochester",
unionLibrary     => "Union",


Then save the file and quit.

We next put links to the Rochester and Union Libraries in the modelCourse so that when we create courses copying templates from the modelCourse, these libraries will be available. Skip this step if you usually only want to use National Problem Library. Note that the Rochester, Union and other libraries are contained in the National Problem Library and are accessible from there under the NPL Directory button in the Library Browser. This step simply creates buttons in the Library Browser so that you can access the Rochester and Union libraries directly.

$cd /opt/webwork/courses/modelCourse/templates/$ ln -s /opt/webwork/libraries/NationalProblemLibrary/Union unionLibrary
$ln -s /opt/webwork/libraries/NationalProblemLibrary/Rochester rochesterLibrary  If you want to put another library into the modelCourse, just do the analogous thing. If you just want the additional library in a particular course, add the link in the templates directory of that course. If you look in the directory /opt/webwork/libraries/NationalProblemLibrary/ you might find other libraries that are not yet listed in global.conf and these can be added in the same way as the Rochester and Union libraries. Finally if you add a library with non standard symbols in the name (e.g. uva-statLibrary) you have to use single quotes when adding it to global.conf, e.g. 'uva-statLibrary' => "UVA-Stat", It's easier to just avoid such names. ### Install and Set Up the CAPA Library This step is optional. It installs and sets up the CAPA Library, which is a library of physics problems. First we download the CAPA Library including required macros. $ cd
$cd downloads$ svn co http://svn.webwork.maa.org/rochester/trunk/rochester_physics_problib


Create a CAPA directory under /opt/webwork and move the CAPA macros there. Then move the CAPA graphics and library files to the required locations and set the group.

$mkdir /opt/webwork/CAPA$ cd rochester_physics_problib/macros/
$mv CAPA_Tools /opt/webwork/CAPA/$ mv CAPA_MCTools /opt/webwork/CAPA/
$cd ..$ mv CAPA_Graphics /opt/webwork/webwork2/htdocs/
$sudo chgrp -R wwdata /opt/webwork/webwork2/htdocs/CAPA_Graphics password: <wwadmin password>$ sudo chmod -R g+w /opt/webwork/webwork2/htdocs/CAPA_Graphics
$cd ..$ mv rochester_physics_problib /opt/webwork/libraries/


We need to edit global.conf again

$cd /opt/webwork/webwork2/conf$ gedit global.conf


Search for courseFiles{problibs} and scroll down several lines to the line

#      capaLibrary      => "CAPA",


Uncomment this line (i.e. remove the #) so it becomes

      capaLibrary      => "CAPA",


Next search for Locations of CAPA resources and, if necessary, edit the four following lines so that they read as follows (cut and paste is the best way to do this)

$pg{specialPGEnvironmentVars}{CAPA_Tools} = "/opt/webwork/CAPA/CAPA_Tools/",$pg{specialPGEnvironmentVars}{CAPA_MCTools}           = "/opt/webwork/CAPA/CAPA_MCTools/",
$pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$webworkDirs{htdocs}/CAPA_Graphics/",
$pg{specialPGEnvironmentVars}{CAPA_Graphics_URL} = "$webworkURLs{htdocs}/CAPA_Graphics/",


Then save the file and quit. Note that we are setting up the CAPA macros and graphics so that they can be used by any WeBWorK course on the server.

There is one final step that is needed. We have to put a link in the templates directory of every course that needs access to the CAPA Library. If you want to have every course you create have access to the CAPA Library (unlikely unless you are in a physics department) put the link in the modelCourse

$cd /opt/webwork/courses/modelCourse/templates/$ ln -s /opt/webwork/libraries/rochester_physics_problib/ capaLibrary


More likely you just want to do this for individual courses. We don't have any yet. But for example after creating myTestCourse below, to set up access to the CAPA Library from myTestCourse, do the following

$cd /opt/webwork/courses/myTestCourse/templates/$ sudo ln -s /opt/webwork/libraries/rochester_physics_problib/ capaLibrary


and do the analogous thing for every course that needs access to the CAPA Library. Then to gain access to the CAPA Library from the course, simply go to the Library Browser and click on the CAPA button.

## Create Your First Actual Course

Since we have edited global.conf a lot and this is a very critical file, it would be a good idea to run

$cd /opt/webwork/webwork2/conf$ diff global.conf global.conf.dist


and check that you haven't made any mistakes (e.g. by introducing an inadvertent line break, etc). If there are any mistakes, correct them. Remember that any time you change global.conf, you must restart the Apache webserver in order for these changes to take effect.

Since we have edited global.conf extensively and haven't restartes Apache we do so now.

$sudo apache2ctl graceful password:<wwadmin password>  Now log into the admin course ( http://yourserver.yourschool.edu/webwork2/admin ) as yourself or admin and 1. click on Add Course 2. For Course ID enter myTestCourse 3. For Course Title enter My Test Course 4. Enter your institution 5. Leave Add WeBWorK administrators to new course checked 6. Add an additional instructor if you wish 7. Copy templates from: modelCourse (the default action) 8. Select sql_single for the database layout (the default action) 9. Click on Add Course 10. Click Log into myTestCourse and log in either as admin or yourself. At some point you will probably want to "hide" myTestCourse from general view but you already know how to do that. ## Test that Things are Working Properly We will test out a few important parts of WeBWorK. If you run into problems, you should look at the Apache error log which is located at /var/log/apache2/error.log. Click on Hmwk Sets Editor on the Main Menu. Then select (by clicking the circle button) Import, select setDemo.def from the from drop down list and select all current users from the assigning this set to drop down list. Then hit Take Action! Now click on Homework Sets on the Main Menu and click on Demo. Then look at the problems. Mathematical equations should be typeset. If not, edit the file Constants.pm in the directory /opt/webwork/webwork2/lib/WeBWorK. Change the line $WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0; to ...::PreserveTempFiles = 1;. Then restart Apache and view the first couple problems or some new ones. Then look in the directory /opt/webwork/webwork2/tmp/. cd to one of the ImageGenerator.../tmp/ directories and look at the error and log files there. When you fix the problem remember to edit ...::PreserveTempFiles = 1; back to 0 and restart Apache or you will be saving a lot of unnecessary files. Another useful trick is to try downloading a hard copy of an assignment and then (assuming there are errors) looking at the various log files that are linked to on the output page.

When you continue looking at problems you will probably get an error when you try to look at Problem 6 because you may not have configured the CAPA macros which are required to display CAPA problems. Unless you are teaching physics you probably don't need them. Also in Problem 9 the Java applet will not load. Problem 9 was written in the 90's and used an applet on a server at The Johns Hopkins University. The server went away a long time ago but we have retained this problem for historical reasons and also because it is a example of several things (e.g. WeBWorK problems can include applets running on remote servers but this can lead to other problems).

Next click on Prob. List to bring back the Problem List Page and click on Download a hardcopy of this homework set. The page is a little complicated because you are a professor (students see a very simple page) but you can just scroll to the bottom and click on Generate hardcopy for selected users and selected sets. You will get an error (because of the bad Problem 6) but just click Download Hardcopy to get what was generated. Also you can see links to various informational files that are available if you run into problems (normally these files are removed if there are no errors).

Another thing to do is to use Email on the Main Menu. Again this page is a little complicated because you can do a lot of things with it (including mail merge) but at this point just select yourself in the list to the right and hit Send Email at the bottom. You should receive two emails. One is the message you just sent and the other is an email with subject "WeBWorK email sent" giving information on your mailing.

As a final test click on Library Browser on the Main Menu. Click Problem Library  and select a Subject, Chapter and Section and then hit View Problems. The first 20 of your selected problems will be displayed. You can also test that you can access any additional Problem Libraries that you installed.

If all the above tests work, you can be pretty confident that WeBWorK is working properly.

Go back to Hmwk Sets Editor on the Main Menu. Then select (by clicking the circle button) Import, select setOrientation.def from the from drop down list and select all current users from the assigning this set to drop down list. Then hit Take Action!. Then go through the Orientation problems. This is a good first set to use for introducing students to WeBWorK.

If you are new to WeBWorK, you should probably add a regular student to myTestCourse and log in as that student to see what the student interface looks like. It's much simpler than the professor interface. Click on Classlist Editor on the Main Menu. Then select (by clicking the circle button) Add 1 student(s)and hit Take Action!. Add one student, say Jane Smith, with Student ID 1234 and Login Name jsmith. Jane Smith's initial password will be her Student ID 1234. Now login as Jane Smith and play around a little.

## Optional Configurations

Optional A stores WeBWorK's "temporary" files in a separate partition. Optional B installs and configures a lightweight webserver to serve static files. Optional C configures Apache so that access to WeBWorK will be through SSL.

### Implement Optional A (wwtmp)

Now is the time to implement Optional A if you choose to do so. Actually you can do this at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that temporary files will be stored in a different location. Note that if you want to use this option but did not create wwtmp. as a separate partition, you first have to create the directory /var/www/wwtmp.

First we set the group and permissions for the wwtmp directory

$su <root password> # cd /var/www # chgrp wwdata wwtmp # chmod ug+w wwtmp # chmod g+s wwtmp # exit$


Next we have to edit global.conf so that WeBWorK uses the new wwtmp directory. Since we have a working WeBWorK system, first we make a backup copy of global.conf.

$cd /opt/webwork/webwork2/conf$ cp global.conf global.conf.bak1
$gedit global.conf  Now edit global.conf. Find the lines $webworkDirs{htdocs_temp}   = "$webworkDirs{htdocs}/tmp";$webworkURLs{htdocs_temp}   = "$webworkURLs{htdocs}/tmp";  and replace them by #$webworkDirs{htdocs_temp}   = "$webworkDirs{htdocs}/tmp"; #$webworkURLs{htdocs_temp}   = "$webworkURLs{htdocs}/tmp";$webworkDirs{htdocs_temp}   = '/var/www/wwtmp';
$webworkURLs{htdocs_temp} = '/wwtmp';  Next find the lines $courseDirs{html_temp}   = "$courseDirs{html}/tmp";$courseURLs{html_temp}   = "$courseURLs{html}/tmp";  and replace them by #$courseDirs{html_temp}   = "$courseDirs{html}/tmp"; #$courseURLs{html_temp}   = "$courseURLs{html}/tmp";$courseDirs{html_temp}   = "/var/www/wwtmp/$courseName";$courseURLs{html_temp}   = "/wwtmp/$courseName";  Then save the file and quit. If you look at the wwtmp directory you will find it empty but after you restart apache and then access some WeBWorK problems, you will find temporary directories and files in wwtmp. Remember your have to restart apache for these changes to take effect. ### Implement Optional B (lighttpd) As is the case for Optional A you can implement Optional B at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that static images and pages will be served by a light weight web server. First we install the light weight webserver lighttpd 1. Open the Synaptic Package Manager (select System, Administration, Synaptic Package Manager). 2. Select Search 3. Search for lighttpd and select it 4. In the pop up window Mark additional required changes? click Mark to accept the requirements. 5. Now click Apply and Apply again to confirm the changes. You can now quit the Synaptic Package Manager. Now we configure lighttpd. First let's make a backup of the configuration file. $ su
# cd /etc/lighttpd
# cp lighttpd.conf lighttpd.conf.bak1


Now edit lighttpd.conf.

# gedit lighttpd.conf


Uncomment the line

#           "mod_status",


so it becomes

           "mod_status",


Apache2 is listening on port 80 so we need an alternate port for lighttp to listen to. Standard alternate ports for this are usually 81, 8000, or 8080. 8080 is the only port that is listed as an official alternate at http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers . Note that in rare cases an installation may block httpd requests to port 8080. If any of your students report that they can not see graphics, they will have to request that access to requests to port 8080 be allowed.

Find the line

# server.port               = 81


uncomment it and change 81 to 8080 so that it reads

server.port               = 8080


Finally uncomment the line

# status.status-url = "/server-status"


so it becomes

  status.status-url = "/server-status"


Then save the file and quit.

Now restart lighttp

$su <root password> # /etc/init.d/lighttpd restart # exit$



Note that you can just run /etc/init.d/lighttpd to get a list of all options.

Now test your server by connecting to "http://localhost:8080/" and/or connecting to your server from a browser on a remote machine. You should see the page It works! indicating that lighttp is running.

You can check lighttp's status by connecting to "http://localhost:8080/server-status" using a browser on your machine or from to "http://yourserver.yourschool.edu:8080/server-status" from a browser on a remote machine.

The Server-Status page doesn't indicate that lighttp is the web server, but it's certainly different than apache's Server-Status page "http://localhost/server-status".

Next we configure WeBWorK to take advantage of lighttp.

First let's make a backup copy of global.conf so that we can easily back out of these changes if necessary.

# cd /opt/webwork/webwork2/conf
# cp global.conf global.conf.bak2


Now edit global.conf. Note that while Optional B is independent of Optional A, we assume most people implementing Optional B will have already implemented Optional A. Therefore we give instructions for editing global.conf assuming that Optional A has been implemented. If this is not the case, modify the instructions below accordingly. Also replace yourserver.yourschool.edu with the correct address.

# gedit global.conf


Find the line

$webworkURLs{htdocs_temp} = '/wwtmp'  and replace it by #$webworkURLs{htdocs_temp}   = '/wwtmp';
$webworkURLs{htdocs_temp} = 'http://yourserver.yourschool.edu:8080/wwtmp';  Find the line $courseURLs{html_temp}   = "/wwtmp/$courseName";  and replace it by #$courseURLs{html_temp}   = "/wwtmp/$courseName";$courseURLs{html_temp}   = "http://yourserver.yourschool.edu:8080/wwtmp/$courseName";  Then save the file and quit. Now restart apache and lighttp. $ sudo apache2ctl graceful
$sudo /etc/init.d/lighttpd restart  To test things go to your test course http://yourserver.yourschool.edu/webwork2/myTestCourse/. Before you login right click on the WeBWorK icon in the upper left hand corner of the login page. The click on Properties (or whatever is appropriate on your browser) and check that the image is being served from port 8080 (something like http://yourserver.yourschool.edu:8080/webwork2_files/images/webwork_rectangle.png. Then log into your course and view a problem with typeset equations (e.g. Problem 1 of the Demo set). Again right click on the typeset equation and check that the image is being served from port 8080. ### Implement Optional C (SSL) Optional C configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. Note that if you implemented Optional B, the non encrypted lighttp server will be used for images, etc but there is no harm in that. I cribbed these directions from several sources, the main one being http://www.akadia.com/services/ssh_test_certificate.html. We will create and work in a tmp directory. $ cd
$mkdir tmp$ cd tmp


First we create an RSA Private Key.

$openssl genrsa -des3 -out server.key 1024  When you are asked for a pass phrase, enter a phrase which we refer to as <my pass phrase> and then confirm it. Next generate a Certificate Signing Request $ openssl req -new -key server.key -out server.csr


Enter the requested information. Important: when you are prompted for the Common Name enter your server's fully qualified domain name, something like yourserver.yourschool.edu. You can leave the last two items

A challenge password []:
An optional company name []:


blank.

One unfortunate side-effect of the pass-phrased private key is that Apache will ask for the pass-phrase each time the web server is started. Obviously this is not necessarily convenient as someone will not always be around to type in the pass-phrase, such as after a reboot or crash. We will remove this but you must keep this file secure.

$cp server.key server.key.bak1$ openssl rsa -in server.key.bak1 -out server.key


Next we generate a self-signed certificate which is good for 365 days

$openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt  Now we become root, move these files, and set their group and permission. $ su
# mv server.crt /etc/ssl/private
# mv server.key /etc/ssl/private
# cd /etc/ssl/private
# chgrp ssl-cert server.*
# chmod 640 server.*


Next we enable the mod_ssl module

# a2enmod ssl


Now we have to configure Apache to use SSL.

# cd /etc/apache2/sites-available/
# cp default default.bak1
# gedit default


Replace the first line

NameVirtualHost *


by the two lines

NameVirtualHost *:80
NameVirtualHost *:443


Now edit the next non blank line

<VirtualHost *>


changing it to

<VirtualHost *:80>


Next copy the entire section

<VirtualHost *:80>
...
</VirtualHost>


(that is the whole VirtualHost section to the end of the file) and paste it into the file at the end of the file. Now we edit this new pasted section. Edit the new second

<VirtualHost *:80>


changing it to

<VirtualHost *:443>


Now at the end of the file just above the line

</VirtualHost>


    SSLEngine on
SSLCertificateFile /etc/ssl/private/server.crt
SSLCertificateKeyFile /etc/ssl/private/server.key


Then save the file and quit. Finally we restart Apache

# apache2ctl graceful


and test things. Connect to https://yourserver.yourschool.edu/webwork2/myTestCourse You will be asked to accept the certificate. After you do so things should work just as before except that all the connection will be via https (except for images, etc if you using lighttp).

Assuming that everything is working, the last thing we do is set things up so that requests to http://yourserver.yourschool.edu/webwork2/ are automatically redirected to https://yourserver.yourschool.edu/webwork2/.

# gedit default


In the

<VirtualHost *:80>


section just above the line

	ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/


Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2


where of course you should edit yourserver.yourschool.edu appropriately. Then save the file and quit. Restart Apache

# apache2ctl graceful


and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.edu/webwork2/.

## Updating WeBWorK files

If you want to update a single WeBWorK file, e.g. /opt/webwork/webwork2/lib/WeBWorK/Utils/FilterRecords.pm you can just do

$cd /opt/webwork/webwork2/lib/WeBWorK/Utils$ sudo cvs update FilterRecords.pm


If you want to update all files in a directory and in all its subdirectories, run the command

$sudo cvs update  form the directory. Note that cvs tries to patch the file on disk with any changes. Usually this works but sometimes it results in a file that will not compile. To avoid this do e.g. the following $ cd /opt/webwork/webwork2/lib/WeBWorK/Utils
$sudo mv FilterRecords.pm FilterRecords.pm.old$ sudo cvs update FilterRecords.pm


Cvs will warn you that the file was lost and then download the new version. You can do a diff between the new and old versions to see what changes have been made. That way you have two files (new and old) and both will compile.

If you want to update the whole WeBWorK system, I would suggest doing the following.

$cd /opt/webwork$ sudo mv webwork2 webwork2_old
\$ sudo mv pg pg_old


and then install the new version of webwork2 and pg following the directions above. That way you can recover you old system simply by moving the old versions back. You also will have an old copy of your configuration files that you probably want when you edit the new ones.

## Where to go From Here

You should play around with myTestCourse e.g. click on Library Browser and browse the Problem Library and also the Rochester and Union libraries.