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/trunk/webwork2$ svn co http://svn.webwork.maa.org/system/trunk/pg



These give you the latest released version

Saving the old system

First we save the old system

$cd /opt/webwork/$ mv webwork2 webwork2_old
$mv pg pg_old  Installing the New System Move the System into the Required Directories $ cd
$cd downloads/$ mv webwork2 /opt/webwork/
$mv pg /opt/webwork/  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, 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. Thus we assume there is a group called wwdata, containing both the WeBWorK administrators and the web server. 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 htdocs/tmp logs tmp
# chmod -R g+w DATA  htdocs/tmp logs tmp
# find DATA/ htdocs/tmp logs/ tmp/ -type d -a ! $$-name .svn -prune$$ -exec chmod g+s {} \;
# exit
$ 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
$cp webwork.apache2-config.dist webwork.apache2-config  Global Configuration Most WeBWorK configuration is done in the file /opt/webwork/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. Most of the global configurations settings you want will be in your old configuration file /opt/webwork/webwork2_old/conf/global.conf. Assuming you have kept your global.conf file up to date, a good way to see if there are changes that you need to make is to do a diff between your old global.conf.dist file and the new one. $ cd /opt/webwork
$diff webwork2/conf/global.conf.dist webwork2_old/conf/global.conf.dist  You should incorporate any changes into your global.conf file. Perhaps a safer procedure is to do a diff between your old global.conf file and the new one (which is a copy of global.conf.dist). $ diff webwork2/conf/global.conf webwork2_old/conf/global.conf


If there are only minor changes to the new global.conf.dist file, you may want to copy your old global.conf file

$cp webwork2_old/conf/global.conf webwork2/conf/global.conf  and then edit it. It there are major changes, you probably want to start with the new version /opt/webwork/webwork2/conf/global.conf and edit is using the old version /opt/webwork/webwork2_old/conf/global.conf as a guide. You should also check to make sure the database.conf file is up to date. $ diff webwork2/conf/database.conf webwork2_old/conf/database.conf


jsMath Settings

Version 2.0 of jsMath introduced a new fallback method for when the TeX fonts are not available on the student's computer. This uses images of the individual TeX characters in place of the TeX fonts. These are distributed in webwork2/htdocs/jsMath/jsMath-fonts.tar.gz, and you need to unpack this tarball before jsMath will work properly. Use the command

$cd /opt/webwork/webwork2/htdocs/jsMath$ 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


You may want to check to see if there are any updates to the modelCourse that you would want to incorporate into your modelCourse.

A good way to see what if anything has been updated recently is to use viewvc: http://webwork.maa.org/viewvc/system/trunk/webwork2/courses.dist/

Note that your modelCourse is already set up at /opt/webwork/courses/modelCourse and probably does not need to be updated. If it needs updating the newer version is at /opt/webwork/webwork2/courses.dist/modelCourse

Restart Apache

$sudo /etc/init.d/apache2 restart  and then check that WeBWorK is working correctly. Check to See if the Database Needs Upgrading If the database structure has changed (e.g. if new columns or tables have been added), you will have to upgrade the database for current courses. If you do not, when you log into a course you will see an error message similar to DBD::mysql::st execute failed: Unknown column 'merge1.enable_reduced_scoring' in 'field list' at /opt/webwork/webwork2/lib/WeBWorK/DB/Schema/NewSQL/Std.pm line 814.  To check the database log into the admin course and select "Upgrade courses". This initially checks the status of courses and does nothing else. If the listing indicates that some courses need their database tables upgraded, select the courses you want to upgrade and click "Upgrade Courses" If Something is Very Wrong Revert Back to Your Old System If something is wrong you can immediately revert back to your old system: $ cd /opt/webwork/
$mv webwork2 webwork2_new$ mv pg pg_new
$mv webwork2_old webwork2$ mv pg_old pg
$sudo /etc/init.d/apache2 restart  You now are using the old system. 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  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.

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.

Consult for other WeBWorK documentation for system administrators.

-- Main.ArnoldPizer - 27 Oct 2010