Difference between revisions of "Upgrading WeBWorK"

From WeBWorK_wiki
Jump to navigation Jump to search
m (→‎Assummed Set Up: Correct typo)
 
(61 intermediate revisions by 5 users not shown)
Line 1: Line 1:
  +
{{Historical}}
  +
  +
* For current information see [[Upgrading_WeBWorK_with_Github]].
  +
* For switching over from using svn to using git and github see [[Github]].
  +
  +
*''See also:'' [[History of WeBWorK version control]]
  +
  +
 
<!-- {{UnderConstruction}} -->
  
<!-- {{UnderConstruction}} -->
−
{{UnderConstruction}}
  
   
−
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.
 +
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.
  
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 ==
 +
== 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 <code>*.conf</code> files.
  +
  +
== Assumed 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
 
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
Line 16: Line 23:
 
* the files and directories are owned by the WeBWorK administrator <code>wwadmin</code>
  
* the files and directories are owned by the WeBWorK administrator <code>wwadmin</code>
 
* files and directories that the webserver (Apache2) needs write access to are in the group <code>wwdata</code>
  
* files and directories that the webserver (Apache2) needs write access to are in the group <code>wwdata</code>
  +
* 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 <code>.bashrc</code> file (or its equivalent) for the WeBWorK administrator <code>wwadmin</code> 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 <code>WEBWORK_ROOT</code> has been required for a long time but <code>PG_ROOT</code> 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 ==
  
== Notation ==
Line 34: Line 51:
 
We will use Subversion to download WeBWorK. Note that the following are rather long commands; it is much easier to copy (<code>^C</code>) them from this document and paste (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>) them in a terminal window.
 
We will use Subversion to download WeBWorK. Note that the following are rather long commands; it is much easier to copy (<code>^C</code>) them from this document and paste (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>) them in a terminal window.
   
−
We assume you are logged in as the WeBWorK administrator (wwadmin) and will download these files to a downloads directory under wwadmin's home directory.
 +
We assume you are logged in as the WeBWorK administrator (<code>wwadmin</code>) and will download these files to the <code>downloads</code> directory under wwadmin's home directory.
   
 
$ cd
  
$ cd
Line 46: Line 63:
   
 
The main information page about WebWork downloads is available at http://webwork.maa.org/wiki/Download
  
The main information page about WebWork downloads is available at http://webwork.maa.org/wiki/Download
−  
   
 
== Saving the old system ==
  
== Saving the old system ==
Line 89: Line 105:
 
# exit
  
# exit
 
$
  
$
  +
  +
=== Updating CPAN modules ===
  +
  +
Run <code> check_modules.pl apache2</code> (or <code> check_modules.pl apache1</code> if you are running apache1) to insure that you have all necessary CPAN modules installed. <code> check_modules.pl</code> is in the <code>/opt/webwork/webwork2/bin/</code> directory which should in in the search path for <code> wwadmin</code>.
  +
See the installation page for instructions on using <code>cpan</code> to update the cpan modules, or update using the cpan modules using the webwork bundle at http://search.cpan.org/~aubreyja/Bundle-WeBWorK-0.01/WeBWorK.pm via the following commands.
  +
  +
$ su
  +
Password: <root password>
  +
# perl -MCPAN -e 'install Bundle::WeBWorK'
  +
  +
The webwork bundle is interactive and will require you to answer yes to many questions.
  +
  +
{{warning}} Later versions of Safe.pm are not compatible with WeBWorK. Use the included module webwork2/lib/WWSafe.pm instead.) Note that
  +
tth is a deprecated method and is no longer used by WeBWorK.
   
 
== Configuring WeBWorK ==
  
== Configuring WeBWorK ==
Line 95: Line 125:
   
 
Before configuring the system, you must make local copies of the <code>global.conf</code> and <code>database.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code> .
 
Before configuring the system, you must make local copies of the <code>global.conf</code> and <code>database.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code> .
−  
 
$ cd /opt/webwork/webwork2/conf
  
$ cd /opt/webwork/webwork2/conf
 
$ cp global.conf.dist global.conf
  
$ cp global.conf.dist global.conf
 
$ cp database.conf.dist database.conf
  
$ cp database.conf.dist database.conf
−
$ cp webwork.apache2-config.dist webwork.apache2-config
  
  +
  +
For versions of WeBWorK greater than 2.5.0, you will also need to make the following local copies of configuration files.
  +
$ cp site.conf.dist site.conf
  +
$ cp localOverrides.conf.dist localOverrides.conf
  +
You may also need to open the file <code>site.conf</code> in a text editor and update the line <code>$database_password = "passwordRW";</code> . The value of <code>$database_password</code> in your new <code>site.conf</code> file should match the value of <code>$database_password</code> from your old <code>global.conf</code> file, which should be located in <code>/opt/webwork/webwork2_old/conf/global.conf</code> .
  +
  +
To create local copies of apache configuration files, you will also need to copy an apache2 or apache1 configuration file, depending on which version of apache you have.
  +
$ cp webwork.apache2-config.dist webwork.apache2-config # for apache2
  +
$ cp webwork.apache-config.dist webwork.apache-config # for apache1
   
 
=== Global Configuration ===
  
=== Global Configuration ===
Line 124: Line 161:
 
You should also check to make sure the <code>database.conf</code> file is up to date.
  
You should also check to make sure the <code>database.conf</code> file is up to date.
 
$ diff webwork2/conf/database.conf webwork2_old/conf/database.conf
  
$ diff webwork2/conf/database.conf webwork2_old/conf/database.conf
  +
  +
Finally there have been small but significant changes to <code>webwork.apache2-config</code>. In particular it defines <code>WEBWORK_ROOT</code> for the webserver. Some features of WeBWorK may fail to work unless this file is up to date.
   
 
=== jsMath Settings ===
  
=== jsMath Settings ===
Line 135: Line 174:
   
   
−
=== Install MathJax ===
 +
=== 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 .
 +
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 <code>/opt/webwork/webwork2/htdocs/mathjax</code>
−  
−
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 ==
  
== Check for updates to courses.dist ==
Line 143: Line 182:
 
You may want to check to see if there are any updates to the modelCourse that you would want to incorporate into your modelCourse.
  
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 viewvcP:
 +
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/
  
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
  
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 and Test ==
Line 156: Line 194:
   
   
−
== Check to see if the database need updating ==
 +
== 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 update the database for current courses. If you do not, when you log into a course you will see an error message similar to
 +
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
  
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.
  
/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==
−  
−
== Restart Apache and Test ==
  
−  
−
Restart Apache
  
−
$ sudo /etc/init.d/apache2 restart
  
−
and then check that WeBWorK is working correctly.
  
−  
−
==If Something is Wrong ==
  
 
If something is wrong you can immediately revert back to your old system:
  
If something is wrong you can immediately revert back to your old system:
 
$ cd /opt/webwork/
  
$ cd /opt/webwork/
Line 181: Line 212:
 
You now are using the old system.
  
You now are using the old system.
   
−
==Install the WeBWorK Problem Libraries ==
 +
==Update the WeBWorK Problem Libraries ==
−
Before we create a real course we will install 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.
   
−
===Install the National Problem Library ===
 +
===Update the National Problem Library ===
−
The <code>National Problem Library</code> 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 <code>global.conf</code>.
  
  +
$ cd /opt/webwork/libraries/NationalProblemLibrary/
  +
$ svn update
   
−
$ cd /opt/webwork/webwork2/conf
  
  +
Now run the <code>NPL-update</code> script making sure you are in the <code>/opt/webwork/libraries/NationalProblemLibrary</code> directory.
−
$ gedit global.conf
  
−  
−
Search for <code>problemLibrary</code> and replace <code>$problemLibrary{root} = "";</code> by <br /> <code>$problemLibrary{root} = "/opt/webwork/libraries/NationalProblemLibrary";</code>
 
−  
−
Then save the file and quit.
  
−  
−
Run the <code>NPL-update</code> script making sure you are in the <code>/opt/webwork/libraries/NationalProblemLibrary</code> directory. This directory contains the files <code>loadDB2</code> and <code>create_tables2.sql</code>.
  
   
 
$ cd /opt/webwork/libraries/NationalProblemLibrary
  
$ cd /opt/webwork/libraries/NationalProblemLibrary
Line 202: Line 227:
 
This has to convert a lot of data for over 20,000 problems so please be patient; it can take a long time.
  
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
  
  +
===Update the CAPA Library ===
−
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.
  
  +
This step is optional. Only do it if you have installed the CAPA Library.
   
−
$ cd /opt/webwork/courses/modelCourse/templates/
  
  +
$ cd /opt/webwork/libraries/rochester_physics_problib
−
$ ln -s /opt/webwork/libraries/NationalProblemLibrary Library
  
  +
$ svn update
−  
−
===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 <code>NPL Directory</code> button.
  
−  
−
First we need to edit <code>global.conf</code> one last time
  
−  
−
$ cd /opt/webwork/webwork2/conf
  
−
$ gedit global.conf
  
−  
−
Search for <code>courseFiles{problibs}</code> and scroll down several lines to the lines
  
−
# rochesterLibrary =&gt; "Rochester",
  
−
# unionLibrary =&gt; "Union",
  
−
Uncomment these lines (i.e. remove the <code>#</code>) so they become
 
−
rochesterLibrary =&gt; "Rochester",
  
−
unionLibrary =&gt; "Union",
  
−
Then save the file and quit.
  
−  
−
We next put links to the Rochester and Union Libraries in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, 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 <code>NPL Directory</code> 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 <code>modelCourse</code>, just do the analogous thing. If you just want the additional library in a particular course, add the link in the <code>templates</code> directory of that course. If you look in the directory <code>/opt/webwork/libraries/NationalProblemLibrary/</code> you might find other libraries that are not yet listed in <code>global.conf</code> and these can be added in the same way as the <code>Rochester and </code><code>Union</code> libraries. Finally if you add a library with non standard symbols in the name (e.g. <code>uva-statLibrary</code>) you have to use single quotes when adding it to <code>global.conf</code>, e.g. <br>
  
−
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>'uva-statLibrary' => "UVA-Stat",</code> <br>
  
−
It's easier to just avoid such names.
  
−  
−
===Install and Set Up the CAPA Library ===
  
−  
−
This step is optional. It installs and sets up [[CAPA Physics Problems|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 <code>CAPA</code> directory under <code>/opt/webwork</code> 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/
  
$ mv CAPA_Graphics /opt/webwork/webwork2/htdocs/
 
$ sudo chgrp -R wwdata /opt/webwork/webwork2/htdocs/CAPA_Graphics
  
$ sudo chgrp -R wwdata /opt/webwork/webwork2/htdocs/CAPA_Graphics
 
password: <wwadmin password>
  
password: <wwadmin password>
 
$ sudo chmod -R g+w /opt/webwork/webwork2/htdocs/CAPA_Graphics
 
$ sudo chmod -R g+w /opt/webwork/webwork2/htdocs/CAPA_Graphics
−
$ cd ..
 
  +
$ cd /opt/webwork/libraries/CAPA/CAPA_Tools
−
$ mv rochester_physics_problib /opt/webwork/libraries/
  
  +
$ svn update
  +
$ cd /opt/webwork/libraries/CAPA/CAPA_MCTools/
  +
$ svn update
   
−
We need to edit <code>global.conf</code> again
  
  +
==Updating Individual WeBWorK files==
−  
−
$ cd /opt/webwork/webwork2/conf
  
−
$ gedit global.conf
  
−  
−
Search for <code>courseFiles{problibs}</code> and scroll down several lines to the line
  
−
# capaLibrary => "CAPA",
  
−
Uncomment this line (i.e. remove the <code>#</code>) so it becomes
 
−
capaLibrary => "CAPA",
  
−  
−
Next search for <code>Locations of CAPA resources</code> 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 <code>modelCourse</code>
  
−  
−
$ 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 <code>myTestCourse</code> below, to set up access to the CAPA Library from <code>myTestCourse</code>, do the following
  
−
$ cd /opt/webwork/courses/myTestCourse/templates/
  
−
$ sudo ln -s /opt/webwork/libraries/rochester_physics_problib/ capaLibrary
  
−
password: <wwadmin password>
  
−  
−
 
−
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 <code>Library Browser</code> and click on the <code>CAPA</code> button.
  
−  
−
==Create Your First Actual Course ==
  
−  
−
Since we have edited <code>global.conf</code> 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
  
−
<code>global.conf</code>, you must restart the Apache webserver in order for these changes to take effect.
 
−  
−
Since we have edited <code>global.conf</code> extensively and haven't restartes Apache we do so now.
  
−
$ sudo apache2ctl graceful
  
−
password:<wwadmin password>
  
−  
−
Now log into the <code>admin</code> course ( <code>http://yourserver.yourschool.edu/webwork2/admin</code> ) as yourself or <code>admin</code> and
 
−
# click on <code>Add Course</code>
  
−
# For <code>Course ID</code> enter <code>myTestCourse</code>
  
−
# For <code>Course Title</code> enter <code>My Test Course</code>
  
−
# Enter your institution
  
−
# Leave <code>Add WeBWorK administrators to new course</code> checked
  
−
# Add an additional instructor if you wish
  
−
# Copy templates from: <code>modelCourse</code> (the default action)
  
−
# Select sql_single for the database layout (the default action)
  
−
# Click on <code>Add Course</code>
  
−
# Click <code>Log into myTestCourse</code>
  
−  
−
and log in either as <code>admin</code> or yourself.
  
−  
−
At some point you will probably want to "hide" <code>myTestCourse</code> 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 <code>/var/log/apache2/error.log</code>.
  
−  
−
Click on <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select (by clicking the circle button) <code>Import</code>, select <code>setDemo.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code>
  
−  
−
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. Then look at the problems. Mathematical equations should be typeset. If not, edit the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code>. Change the line <code>$WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0;</code> to <code>...::PreserveTempFiles = 1;</code>. Then restart Apache and view the first couple problems or some new ones. Then look in the directory <code>/opt/webwork/webwork2/tmp/</code>. <code>cd</code> to one of the <code>ImageGenerator.../tmp/</code> directories and look at the error and log files there. When you fix the problem remember to edit <code>...::PreserveTempFiles = 1;</code> 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 <code>Prob. List</code> to bring back the Problem List Page and click on <code>Download a hardcopy of this homework set</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. You will get an error (because of the bad Problem 6) but just click <code>Download Hardcopy</code> 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 <code>Email</code> on the <code>Main Menu</code>. 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 <code>Send Email</code> 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 <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Problem Library </code>
  
−
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. 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 <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select (by clicking the circle button) <code>Import</code>, select <code>setOrientation.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code>. 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 <code>Classlist Editor</code> on the <code>Main Menu</code>.
  
−
Then select (by clicking the circle button) <code>Add 1 student(s)</code>and hit <code>Take Action!</code>. Add one student, say Jane Smith, with <code>Student ID</code> <code>1234</code> and <code>Login Name</code> <code>jsmith</code>.
  
−
Jane Smith's initial password will be her <code>Student ID</code> <code>1234</code>. 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 <code>wwtmp</code>. as a separate partition, you first have to create the directory <code>/var/www/wwtmp</code>.
  
−  
−
First we set the group and permissions for the <code>wwtmp</code> directory
  
−  
−
$ su
  
−
<root password>
  
−
# cd /var/www
  
−
# chgrp wwdata wwtmp
  
−
# chmod ug+w wwtmp
  
−
# chmod g+s wwtmp
  
−
# exit
  
−
$
  
−  
−
Next we have to edit <code>global.conf</code> so that WeBWorK uses the new <code>wwtmp</code> directory. Since we have a working WeBWorK system, first we make a backup copy of <code>global.conf</code>.
  
−  
−  
−
$ cd /opt/webwork/webwork2/conf
  
−
$ cp global.conf global.conf.bak1
  
−
$ gedit global.conf
  
−  
−
Now edit <code>global.conf</code>. 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 <code>wwtmp</code> 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 <code>wwtmp</code>. 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 <code>lighttpd</code>
  
−  
−
# Open the <code>Synaptic Package Manager</code> (select <code>System</code>, <code>Administration</code>, <code>Synaptic Package Manager</code>).
 
−
# Select <code>Search</code>
 
−
# Search for <code>lighttpd</code> and select it
  
−
# In the pop up window <code>Mark additional required changes?</code> click <code>Mark</code> to accept the requirements.
  
−
# Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes.
  
−  
−
You can now quit the <code>Synaptic Package Manager</code>.
  
−  
−
Now we configure <code>lighttpd</code>. First let's make a backup of the configuration file.
  
−  
−  
−
$ su
  
−
<root password>
  
−
# cd /etc/lighttpd
  
−
# cp lighttpd.conf lighttpd.conf.bak1
  
−  
−
Now edit <code>lighttpd.conf</code>.
 
−  
−
# 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 <code>/etc/init.d/lighttpd</code> 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 <code>global.conf</code> 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 <code>global.conf</code>. 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 <code>yourserver.yourschool.edu</code> 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
  
−
password:<wwadmin password>
  
−
$ sudo /etc/init.d/lighttpd restart
  
−  
−
To test things go to your test course <code>http://yourserver.yourschool.edu/webwork2/myTestCourse/</code>. 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 <code>http://yourserver.yourschool.edu:8080/webwork2_files/images/webwork_rectangle.png</code>. 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 <code>tmp</code> 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 <code>pass phrase</code>, enter a phrase which we refer to as <code>&lt;my pass phrase&gt;</code> 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 <code>Common Name</code> enter your server's fully qualified domain name, something like <code>yourserver.yourschool.edu</code>. 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
  
−
<root password>
  
−
# 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 <code>mod_ssl</code> 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>
  
−
add the three lines
  
−
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/
  
−
add the line
  
−
Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2
  
−
where of course you should edit <code>yourserver.yourschool.edu</code> 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. <code>/opt/webwork/webwork2/lib/WeBWorK/Utils/FilterRecords.pm</code> you can just do
  
If you want to update a single WeBWorK file, e.g. <code>/opt/webwork/webwork2/lib/WeBWorK/Utils/FilterRecords.pm</code> you can just do
 
$ cd /opt/webwork/webwork2/lib/WeBWorK/Utils
  
$ cd /opt/webwork/webwork2/lib/WeBWorK/Utils
−
$ sudo cvs update FilterRecords.pm
  
  +
First do
−
If you want to update all files in a directory and in all its subdirectories, run the command
 
  +
$ svn status -u
−
$ sudo cvs update
 
  +
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.
−
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
  
  +
To update the file use
−
$ cd /opt/webwork/webwork2/lib/WeBWorK/Utils
  
  +
svn update FilterRecords.pm
−
$ 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 <code>diff</code> 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.
 +
If you want to update all files in a directory and in all its subdirectories, run the command
−
$ cd /opt/webwork
 +
$ svn update
−
$ sudo mv webwork2 webwork2_old
 +
from the directory.
−
$ sudo mv pg pg_old
  
−
and then install the new version of <code>webwork2</code> and <code>pg</code> 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 <code>myTestCourse</code> e.g. click on <code>Library Browser</code> and browse the <code>Problem Library</code> and also the <code>Rochester</code> and <code>Union</code> libraries.
  
   
−
Look at http://webhost.math.rochester.edu/webworkdocs/docs/courseadmin/usingwebwork
  
   
−
Read [[Course Administration]] for more information about creating courses.
  
   
 
Consult [[Category:Administrators]] for other WeBWorK documentation for system administrators.
  
Consult [[Category:Administrators]] for other WeBWorK documentation for system administrators.
   
−
-- Main.ArnoldPizer - 15 Dec 2009 <br />
 +
-- Main.ArnoldPizer - 27 Oct 2010 <br />
   
 
[[Category:Installation Manuals]]
  
[[Category:Installation Manuals]]
  +
[[Category:Installation]]

Latest revision as of 13:02, 25 January 2022

This article has been retained as a historical document. It is not up-to-date and the formatting may be lacking. Use the information herein with caution.


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.

Assumed 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 check_modules.pl apache2 (or check_modules.pl apache1 if you are running apache1) to insure that you have all necessary CPAN modules installed. check_modules.pl is in the /opt/webwork/webwork2/bin/ directory which should in in the search path for wwadmin. See the installation page for instructions on using cpan to update the cpan modules, or update using the cpan modules using the webwork bundle at http://search.cpan.org/~aubreyja/Bundle-WeBWorK-0.01/WeBWorK.pm via the following commands. 

$ su
Password: <root password>
# perl -MCPAN -e 'install Bundle::WeBWorK'

The webwork bundle is interactive and will require you to answer yes to many questions.

Warning : Later versions of Safe.pm are not compatible with WeBWorK. Use the included module webwork2/lib/WWSafe.pm instead.) Note that tth is a deprecated method and is no longer used by WeBWorK.

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

For versions of WeBWorK greater than 2.5.0, you will also need to make the following local copies of configuration files. 

$ cp site.conf.dist site.conf
$ cp localOverrides.conf.dist localOverrides.conf

You may also need to open the file site.conf in a text editor and update the line $database_password = "passwordRW"; . The value of $database_password in your new site.conf file should match the value of $database_password from your old global.conf file, which should be located in /opt/webwork/webwork2_old/conf/global.conf .

To create local copies of apache configuration files, you will also need to copy an apache2 or apache1 configuration file, depending on which version of apache you have. 

$ cp webwork.apache2-config.dist webwork.apache2-config    # for apache2
$ cp webwork.apache-config.dist webwork.apache-config      # for apache1

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

Retrieved from "https://webwork.maa.org/mediawiki_new/index.php?title=Upgrading_WeBWorK&oldid=22562"