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. If you only want to update individual files see Upgrading_WeBWorK#Updating_Individual_WeBWorK_files

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.

Release notes

Please read, or at least review, the release notes for the update.

They can be found in Category:Release_Notes.

This will inform you of new features and alert you to any special measures that need to be taken when updating the *.conf files.

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
• Check that the webwork directory has been added to your PATH and that WEBWORK_ROOT and PG_ROOT are defined (Installation_Manual_for_2.4_on_Ubuntu_10.04#Configuring_the_Shell). If this is not done some of the command line scripts called below will not execute.

Required Environmental Variables

Check that the .bashrc file (or its equivalent) for the WeBWorK administrator wwadmin contains the lines:

export PATH=$PATH:/opt/webwork/webwork2/bin
export WEBWORK_ROOT=/opt/webwork/webwork2
export PG_ROOT=/opt/webwork/pg

The environmental variable WEBWORK_ROOT has been required for a long time but PG_ROOT is newly required as of WeBWorK version 2.4.9. Both are needed to run the command line scripts found in /opt/webwork/webwork2/bin.

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

Downloading the WeBWorK System Software

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.

We assume you are logged in as the WeBWorK administrator (wwadmin) and will download these files to the downloads directory under wwadmin's home directory.

$ 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

The main information page about WebWork downloads is available at http://webwork.maa.org/wiki/Download

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
Password: <root password>
# 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
$

Updating CPAN modules

Run webwork2/bin/check_modules.pl (or webwork2/bin/check_modules.pl apache2 if you are running apache2) to insure that you have all necessary CPAN modules installed. See the installation page for instructions on using cpan to update the cpan modules. (Warning: later versions of Safe.pm are not compatible with WeBWorK. Use the included module webwork2/lib/WWSafe.pm instead. )

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

Finally there have been small but significant changes to webwork.apache2-config. In particular it defines WEBWORK_ROOT for the webserver. Some features of WeBWorK may fail to work unless this file is up to date.

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.

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 . MathJax is already installed in the location /opt/webwork/webwork2/htdocs/mathjax

Check for updates to courses.dist

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 and Test

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.

Update the WeBWorK Problem Libraries

Changes to Problem Libraries are almost always isolated and independent of each other (e.g. editing exiting problems or adding new ones). Thus unless you want to be incredibly careful, there should be no reason to make a backup copy of a library before updating it.

Update the National Problem Library

$ cd /opt/webwork/libraries/NationalProblemLibrary/
$ svn update

Now run the NPL-update script making sure you are in the /opt/webwork/libraries/NationalProblemLibrary directory.

$ 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.

Update the CAPA Library

This step is optional. Only do it if you have installed the CAPA Library.

$ cd /opt/webwork/libraries/rochester_physics_problib                                                  
$ svn update                                                                      
$ 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 /opt/webwork/libraries/CAPA/CAPA_Tools
$ svn update 
$ cd /opt/webwork/libraries/CAPA/CAPA_MCTools/
$ svn update

Updating Individual 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

First do

$ svn status -u

This gives you the status of all files in the directory. For an explanation of the output see http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.status.html.

To update the file use

svn update FilterRecords.pm

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

$ svn update 

from the directory.

Consult for other WeBWorK documentation for system administrators.

-- Main.ArnoldPizer - 27 Oct 2010