Upgrading WeBWorK from 2.15 to 2.16

These instructions are intended to help you upgrade from WeBWorK 2.15 to 2.16. This assumes that you have an existing WeBWorK 2.15 system and want to maintain all of your courses and student data.

WARNING: The github branch for the latest version of WeBWorK has changed! It is now main, instead of master. The "Downloading the new version" section in the instructions below tells how to change your branch before attempting to update. Otherwise "git pull" will not work.

Upgrading from 2.14 or earlier

If you are upgrading from a version 2.14 or earlier, you will have to modify your database so that it uses the utf8mb4 character set. There are two approaches:

1. Run the /opt/webwork/bin/upgrade-database-to-utf8mb4.pl script. This script was only added in WeBWorK 2.16, so you will need to check out the WeBWorK 2.16 code (see below) in order for the script to be available, or
2. Follow the instructions at Converting the webwork database from the latin1 to the utf8mb4 character set

Upgrading from 2.15

Prerequisites

WeBWorK 2.16 requires several new packages

• npm
  • Ubuntu: sudo apt install npm
  • CentOS/RHEL: sudo yum install npm
• HTTP::Async
  • Ubuntu: sudo apt install libhttp-async-perl
  • CentOS/RHEL: sudo cpanm HTTP::Async
• CGI::Cookie
  • Ubuntu 20.04: sudo apt install libcgi-pm-perl
  • CentOS/RHEL and older Ubuntu: sudo cpanm CGI::Cookie
• Archive::Zip
  • Ubuntu: sudo apt install libarchive-zip-perl
  • CentOS/RHEL: sudo yum install perl-Archive-Zip
• It is strongly recommended that you switch from DBD::mysql to DBD::MariaDB, so you should install DBD::MariaDB
  • Ubuntu: sudo apt install libdbd-mariadb-perl
  • CentOS/RHEL:
    • You will probably need to install the mariadb-devel package first: sudo yum install mariadb-devel
    • sudo cpanm DBD::MariaDB
• SQL::Abstract::Classic - WeBWorK is currently not compatible with versions of SQL::Abstract beyond 1.87. You can check your version of SQL::Abstract with the following command: perl -MSQL::Abstract -e 'print $SQL::Abstract::Version ."\n";' If this reports a version >1.87, then you should install SQL::Abstract::Classic:
  • Ubuntu and CentOS/RHEL: cpanm SQL::Abstract::Classic
• dvisvgm (required if you wish to use TikZ images in PG problems)
  • Ubuntu: sudo apt install dvisvgm
  • CentOS/RHEL: sudo yum install divsvgm
• pdf2svg (required if you wish to use TikZ images in PG problems)
  • Ubuntu: sudo apt install pdf2svg
  • CentOS/RHEL: Not currently packaged
• ImageMagick (required if you wish to use TikZ images in PG problems)
  • Ubuntu: sudo apt install imagemagick
  • CentOS/RHEL: sudo yum install imagemagick

Configuration Files

There have been significant changes to the configuration files (site.conf and localOverrides.conf). It is strongly recommended that you create new copies of the configuration files from the distribution versions, and recreate any custom settings that you have added. Before you check out the new WeBWorK software, make a note of any changes you have made to these two files:

 cd /opt/webwork/webwork2/conf
 diff site.conf site.conf.dist
 diff localOverrides.conf localOverrides.conf.dist

This will tell you what settings you have customized in the config files. Make a note of these so that they can be recreated in the new version.

It is recommended that you save a copy of the old versions of your versions of site.conf and localOverrides.conf in a "safe" place. Ex:

 cd /opt/webwork/webwork2/conf
 cp -a site.conf localOverrides.conf ~/

Later on we recommend saving the old files with a different name in this directory, so the spare copy is a fallback.

Downloading the new version

As of 2.16, the default branch in Github for the webwork2 and pg repositories is now main instead of master. If you have a local clone with the old master branch, then you can switch to main with

git branch -m master main
git fetch origin
git branch -u origin/main main
git remote set-head origin -a

Once you have switched to main, you can update the code to version 2.16 by running

git merge

Updating the Configuration Files

As recommended above, you should rebuild localOverrides.conf and site.conf from the corresponding .dist files

 cd /opt/webwork/webwork2/conf
 mv site.conf site.conf.2.15
 cp -p site.conf.dist site.conf
 mv localOverrides.conf localOverrides.conf.2.15
 cp -p localOverrides.conf.dist localOverrides.conf

You will then need to edit site.conf and provide some basic information (e.g. site url, database connection information). Note that the format for database configuration has changed significantly, so it is not sufficient to copy this from your old site.conf file.

If you have not changed any of the WeBWorK defaults, then you will not need to edit localOverrides.conf.

Check for missing dependencies

Now is a good time to run check_modules.pl to make sure that you are not missing any of the dependencies.

Install the Necessary Javascript Packages

As of WeBWorK 2.16, javascript dependencies are handled by npm. To install the requisite javascript, run

 cd /opt/webwork/webwork2/htdocs
 npm install

Note that MathJax is handled by this process as well, so once you have version 2.16 up and running you can safely delete the /opt/webwork/MathJax folder.

Upgrade the database

Due to changes to the database, you may need to run upgrade_admin_db.pl before logging in to the admin course.

You should now be in a position to start apache. Before accessing any of your existing courses, you should upgrade the database by logging into the admin course and running "Upgrade Courses".

Gotchas

Problem with overline, etc. in MathJax in Firefox

Due to a browser bug in Firefox, \overline and related things are not displaying properly in Firefox at some zoom levels when MathJax is being used to display the equations. At present, there is no known reasonable server-side workaround from the WeBWorK side. Students using Firefox could change their account settings to use images to display equations, but may be better off just using a different browser when working on WeBWorK at present. More details about the issue can be found in issue 1524 on GitHub. An Mozilla bug report was filed on the Mozilla BugZilla site, and people are invited to add their comments on the impact of the bug there.

MariaDB vs. mysql

WeBWorK currently supports recent versions of either MariaDB or mysql as the database server, but the majority of development is being done with MariaDB as the database server, so in the future MariaDB may be better supported. If you choose to migrate from mysql to MariaDB, beware that Ubuntu systems do not automatically delete the AppArmor profile for mysql when you remove mysql and replace it with MariaDB. See https://stackoverflow.com/questions/40997257/mysql-service-fails-to-start-hangs-up-timeout-ubuntu-mariadb for details on how to fix this.

LTI Changes

If you are using the LTI integration with your LMS, note that the code that determines what to use for a username has been rewritten. The defaults should behave the same as previous versions, but WeBWorK 2.16 does not automatically look for an alternative source of username if the preferred source is not provided by the LMS. See the notes in authen_LTI.conf.dist for more information.

The manner in which student_id is set was also changed for WeBWork 2.16. It will only be set using the field requested by the setting $preferred_source_of_student_id and will no longer automatically use 'custom_student_id' as a forced value if the LMS sent that.

Missing LaTeX style file

WeBWorK 2.16 uses the iftex.sty file when creating hardcopies (pdfs) of homework sets. On Ubuntu this file is likely already available. On RHEL/CentOS if you get an error about that file being missing when generating a hardcopy, it can be installed using

 yum install texlive-iftex

Clear Your Browser Cache

WeBWorK 2.16 changes the way that javascript dependencies are handled, which means that after the upgrade all users should clear their browser cache. If things aren't displaying properly, try holding down the shift key and reloading the page.