View source for Upgrading WeBWorK from 2.15 to 2.16

{{UnderConstruction}}
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.

= 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:
# Run the <code>/opt/webwork/bin/upgrade-database-to-utf8mb4.pl</code> 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
# 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: <code>sudo apt install npm</code>
** CentOS/RHEL: <code>sudo yum install npm</code>
* HTTP::Async
** Ubuntu: <code>sudo apt install libhttp-async-perl</code>
** CentOS/RHEL: <code>sudo cpanm HTTP::Async</code>
* CGI::Cookie
** Ubuntu 20.04: <code>sudo apt install libcgi-pm-perl</code>
** CentOS/RHEL and older Ubuntu: <code>sudo cpanm CGI::Cookie</code>
* Archive::Zip
** Ubuntu: <code>sudo apt install libarchive-zip-perl</code>
** CentOS/RHEL: <code>sudo yum install perl-Archive-Zip</code>
* It is strongly recommended that you switch from DBD::mysql to DBD::MariaDB, so you should install DBD::MariaDB
** Ubuntu: <code>sudo apt install libdbd-mariadb-perl</code>
** CentOS/RHEL:
*** You will probably need to install the mariadb-devel package first: <code>sudo yum install mariadb-devel</code>
*** <code>sudo cpanm DBD::MariaDB</code>
* 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:
<code>perl -MSQL::Abstract -e 'print $SQL::Abstract::Version ."\n";'</code>
If this reports a version >1.87, then you should install SQL::Abstract::Classic:
** Ubuntu and CentOS/RHEL: <code>cpanm SQL::Abstract::Classic</code>
* dvisvgm (required if you wish to use TikZ images in PG problems)
** Ubuntu: <code>sudo apt install dvisvgm</code>
** CentOS/RHEL: <code>sudo yum install divsvgm</code>
* pdf2svg (required if you wish to use [[TikZImages|TikZ images in PG problems]])
** Ubuntu: <code>sudo apt install pdf2svg</code>
** CentOS/RHEL: Not currently packaged
* ImageMagick (required if you wish to use [[TikZImages|TikZ images in PG problems]])
** Ubuntu: <code>sudo apt install imagemagick</code>
** CentOS/RHEL: <code>sudo yum install imagemagick</code>


== Configuration Files ==
There have been significant changes to the configuration files (site.conf and localOverrides.conf.dist).  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.

== Downloading the new version ==
As of 2.16, the default branch of the webwork2 and pg repositories 

= Gotchas =
== 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.