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:

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

$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  ## 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
$sudo chmod -R g+w /opt/webwork/webwork2/htdocs/CAPA_Graphics$ cd /opt/webwork/CAPA/CAPA_Tools
$svn update$ cd /opt/webwork/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