Difference between revisions of "Installation Manual for 2.18 on Ubuntu"

From WeBWorK_wiki
Jump to navigation Jump to search
 
(221 intermediate revisions by 7 users not shown)
Line 1: Line 1:
  +
  +
<!-- {{UnderConstruction}} -->
  +
 
These instructions cover the installation of WeBWorK 2.18 for Ubuntu Server 22.04 LTS.
 
These instructions cover the installation of WeBWorK 2.18 for Ubuntu Server 22.04 LTS.
   
Other installation methods (which are faster and easier) include using the WeBWorK Virtual Machine Image (see [[Installing WeBWorK from a Virtual Machine Image]]) which has been tested on VMware, VirtualBox and QEMU/KVM and using the WeBWorK AMI if you want to run your server on AWS (see [[WeBWorK Amazon Machine Images (AMI's)]]).
+
Other installation methods (which are faster and easier) include using the WeBWorK Virtual Machine Image (see [[Installing WeBWorK from a Virtual Machine Image]]) which has been tested on VMware, VirtualBox and QEMU/KVM and using the WeBWorK AMI if you want to run your server on AWS (see [[WeBWorK Amazon Machine Images (AMI's)]]).
   
  +
<!-- Note that the Virtual Machine Image for the latest version of WeBWorK may not be available at the time of release. -->
   
If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Upgrading_WeBWorK_from_2.17_to_2.18]].
+
If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Release notes for WeBWorK 2.18#Upgrade Instructions]].
   
 
== Notation ==
 
== Notation ==
   
First some short comments on notation we will be using. We will use <code>&lt;key&gt;</code> to indicate that you should press a specific key (e.g. <code>&lt;Enter&gt;</code>, <code>&lt;Tab&gt;</code>, <code>&lt;F12&gt;</code>, etc.). Sometimes we will also use e.g. <code>&lt;wwadmin password&gt;</code> to indicate you have to enter the wwadmin password. Note that we will use <code>wwadmin</code> to refer to your administrative user on the system. In practice you should NOT actually use wwadmin for your administrative user name. Using a fixed user name that is publicly known is a security vulnerability.
 
  +
First some short comments on notation we will be using.
  +
  +
We will use <code>&lt;key&gt;</code> to indicate that you should press a specific key (e.g. <code>&lt;Enter&gt;</code>, <code>&lt;Tab&gt;</code>, <code>&lt;F12&gt;</code>, etc.).
  +
  +
Note that we will use <code>wwadmin</code> to refer to your administrative user on the system. In practice you should NOT actually use wwadmin for your administrative user name. Using a fixed user name that is publicly known is a security vulnerability.
   
 
<code>^</code> will indicate the <code>&lt;Ctrl&gt;</code> key so e.g. <code>^X</code> is really shorthand for <code>&lt;Ctrl&gt; &lt;X&gt;</code>, i.e. press the Ctrl key and hit the X key.
 
<code>^</code> will indicate the <code>&lt;Ctrl&gt;</code> key so e.g. <code>^X</code> is really shorthand for <code>&lt;Ctrl&gt; &lt;X&gt;</code>, i.e. press the Ctrl key and hit the X key.
   
Code blocks begin with <code>$</code>. You are not intended to type the <code>$</code> character as part of the provided commands. Note that many commands begin with <code>sudo</code>. These commands are executed with super user privileges. You will need to enter your password for the first invocation of one of these commands which will begin a super user session. That session will timeout typically 15 minutes after the last entered sudo command. You can also enter a super user shell with <code>sudo -s</code>. However, it is not advisable to do so. This is an unsafe practice. Forgetting to exit the super user shell is a common mistake that can lead to disastrous consequences if the wrong command is executed with the elevated privileges.
 
  +
Code blocks for command to enter in the shell begin with <code>$</code>. You are not intended to type the <code>$</code> character as part of the provided commands.
  +
  +
Note that many commands begin with <code>sudo</code>. These commands are executed with super user privileges. You will need to enter your password for the first invocation of one of these commands which will begin a super user session. That session will timeout typically 15 minutes after the last entered sudo command, and you will need to enter your password again. You can also enter a super user shell with <code>sudo -s</code>. However, it is not advisable to do so. This is an unsafe practice. Forgetting to exit the super user shell is a common mistake that can lead to disastrous consequences if the wrong command is executed with the elevated privileges.
   
== Installing the Ubuntu 22.04 Server Operating System ==
+
== Install the Ubuntu 22.04 Server Operating System ==
   
 
===Installation===
 
===Installation===
Line 23: Line 33:
 
Enter the information for the steps until you get to the "Profile setup".
 
Enter the information for the steps until you get to the "Profile setup".
 
;Profile Setup
 
;Profile Setup
What you fill in for the "Profile setup" is a privileged user so you might want to enter a special administrative account rather than your normal account. We suggest <code>wwadmin</code> but you can use whatever you want.
+
What you fill in for the "Profile setup" is a privileged user so you might want to enter a special administrative account rather than your normal account. You can use whatever you want. Do NOT use <code>wwadmin</code>, but this is what will be referred to in these instructions by <code>wwadmin</code>.
 
* Enter the information for "Your name"
 
* Enter the information for "Your name"
 
* Enter the information for "Your Computer's name"
 
* Enter the information for "Your Computer's name"
 
* Enter the information for "Pick a username" '''In these instructions, we will call this name <code>wwadmin</code>.'''
 
* Enter the information for "Pick a username" '''In these instructions, we will call this name <code>wwadmin</code>.'''
* Enter the information twice for the password. '''In these instructions, we will call this password the <code>&lt;wwadmin password&gt;</code>.''' '''DO NOT FORGET WHAT YOU ENTER HERE.'''
+
* Enter the information twice for the password. '''In these instructions, you will need to enter this password for <code>sudo</code> commands.''' '''DO NOT FORGET WHAT YOU ENTER HERE.'''
   
 
* Then select <code>Done</code> and press <code>&lt;Enter&gt;</code>.
 
* Then select <code>Done</code> and press <code>&lt;Enter&gt;</code>.
Line 37: Line 47:
 
;Featured Server Snaps
 
;Featured Server Snaps
 
: Do not select any server snaps. Then select <code>Done</code> and press <code>&lt;Enter&gt;</code>.
 
: Do not select any server snaps. Then select <code>Done</code> and press <code>&lt;Enter&gt;</code>.
 
   
 
Now sit back and relax while the installation takes place. This should be pretty quick. When you finally see "Reboot Now", press <code>&lt;Enter&gt;</code> and log into your server.
 
Now sit back and relax while the installation takes place. This should be pretty quick. When you finally see "Reboot Now", press <code>&lt;Enter&gt;</code> and log into your server.
Line 56: Line 65:
 
...
 
...
 
Here 192.168.76.128 is the ip address of your server. Note that you should ignore the loopback address 127.0.0.1.
 
Here 192.168.76.128 is the ip address of your server. Note that you should ignore the loopback address 127.0.0.1.
  +
  +
=== Fully Qualified Domain Name ===
  +
Now we have to set your server's fully qualified domain name. Note that if your network was set up automatically via DHCP, your server's fully qualified domain name should already be set up. You can check by running the <code>hostname</code> commands below.
  +
  +
Run the command
  +
sudo hostnamectl set-hostname webwork
  +
where of course you should replace webwork by whatever your server's name is.
  +
  +
You can check these settings by running the commands
  +
  +
$ hostname --fqdn
  +
and
  +
$ hostname
  +
  +
The first gives the server's fully qualified domain name (e.g. webwork.mydepartment.myschool.edu) and the second the server's name (e.g. webwork).
   
 
==Install Software Packages==
 
==Install Software Packages==
Line 61: Line 85:
 
=== Ubuntu Software Packages ===
 
=== Ubuntu Software Packages ===
   
On Ubuntu and other Debian linuxes, the following instructions will get needed software packages installed. You may first have to run the commands
+
The following instructions will install necessary software packages. You may first have to run the commands
 
$ sudo apt update
 
$ sudo apt update
 
$ sudo apt upgrade
 
$ sudo apt upgrade
Line 68: Line 92:
 
Here is the list of Ubuntu packages that need to be installed.
 
Here is the list of Ubuntu packages that need to be installed.
   
  +
# <code>cm-super</code>
 
# <code>cpanminus</code>
 
# <code>cpanminus</code>
 
# <code>curl</code>
 
# <code>curl</code>
Line 77: Line 102:
 
# <code>libarchive-zip-perl</code>
 
# <code>libarchive-zip-perl</code>
 
# <code>libarray-utils-perl</code>
 
# <code>libarray-utils-perl</code>
# <code>libcrypt-ssleay-perl</code>
+
# <code>libclass-tiny-antlers-perl</code>
  +
# <code>libcrypt-jwt-perl</code>
  +
# <code>libcryptx-perl</code>
 
# <code>libdata-dump-perl</code>
 
# <code>libdata-dump-perl</code>
# <code>libdata-structure-utils-perl</code>
+
# <code>libdata-structure-util-perl</code>
 
# <code>libdatetime-perl</code>
 
# <code>libdatetime-perl</code>
# <code>libemail-address-xs-perl</code>
 
# <code>libemail-sender-perl</code>
 
 
# <code>libemail-stuffer-perl</code>
 
# <code>libemail-stuffer-perl</code>
 
# <code>libexception-class-perl</code>
 
# <code>libexception-class-perl</code>
# <code>libextutils-xsbuilder-perl</code>
+
# <code>libfile-find-rule-perl</code>
# <code>libfile-find-rule-perl-perl</code>
 
 
# <code>libfile-sharedir-install-perl</code>
 
# <code>libfile-sharedir-install-perl</code>
 
# <code>libfuture-asyncawait-perl</code>
 
# <code>libfuture-asyncawait-perl</code>
Line 92: Line 115:
 
# <code>libiterator-perl</code>
 
# <code>libiterator-perl</code>
 
# <code>libiterator-util-perl</code>
 
# <code>libiterator-util-perl</code>
  +
# <code>libjson-maybexs-perl</code>
 
# <code>libjson-perl</code>
 
# <code>libjson-perl</code>
 
# <code>liblocale-maketext-lexicon-perl</code>
 
# <code>liblocale-maketext-lexicon-perl</code>
# <code>libmime-tools-perl</code>
+
# <code>libmath-random-secure-perl</code>
  +
# <code>libminion-perl</code>
  +
# <code>libminion-backend-sqlite-perl</code>
 
# <code>libmojolicious-perl</code>
 
# <code>libmojolicious-perl</code>
  +
# <code>libmojolicious-plugin-renderfile-perl</code>
 
# <code>libnet-ip-perl</code>
 
# <code>libnet-ip-perl</code>
 
# <code>libnet-ldap-perl</code>
 
# <code>libnet-ldap-perl</code>
Line 101: Line 126:
 
# <code>libossp-uuid-perl</code>
 
# <code>libossp-uuid-perl</code>
 
# <code>libpadwalker-perl</code>
 
# <code>libpadwalker-perl</code>
  +
# <code>libpandoc-wrapper-perl</code>
 
# <code>libpath-class-perl</code>
 
# <code>libpath-class-perl</code>
 
# <code>libphp-serialization-perl</code>
 
# <code>libphp-serialization-perl</code>
 
# <code>libpod-wsdl-perl</code>
 
# <code>libpod-wsdl-perl</code>
 
# <code>libsoap-lite-perl</code>
 
# <code>libsoap-lite-perl</code>
# <code>libsql-abstract-perl</code>
 
 
# <code>libsql-abstract-classic-perl</code>
 
# <code>libsql-abstract-classic-perl</code>
 
# <code>libstring-shellquote-perl</code>
 
# <code>libstring-shellquote-perl</code>
 
# <code>libsvg-perl</code>
 
# <code>libsvg-perl</code>
 
# <code>libtemplate-perl</code>
 
# <code>libtemplate-perl</code>
# <code>libtest-exception-perl</code>
 
# <code>libtest-fatal-perl</code>
 
# <code>libtest-mockobject-perl</code>
 
# <code>libtest-requires-perl</code>
 
# <code>libtest-warn-perl</code>
 
 
# <code>libtext-csv-perl</code>
 
# <code>libtext-csv-perl</code>
 
# <code>libtimedate-perl</code>
 
# <code>libtimedate-perl</code>
# <code>libtype-tiny-perl</code>
 
 
# <code>libuniversal-can-perl</code>
 
# <code>libuniversal-can-perl</code>
 
# <code>libuniversal-isa-perl</code>
 
# <code>libuniversal-isa-perl</code>
Line 127: Line 146:
 
# <code>make</code>
 
# <code>make</code>
 
# <code>netpbm</code>
 
# <code>netpbm</code>
# <code>npm</code>
 
 
# <code>openssh-server</code>
 
# <code>openssh-server</code>
 
# <code>pdf2svg</code>
 
# <code>pdf2svg</code>
Line 133: Line 151:
 
# <code>texlive</code>
 
# <code>texlive</code>
 
# <code>texlive-latex-extra</code>
 
# <code>texlive-latex-extra</code>
  +
# <code>texlive-science</code>
 
# <code>unzip</code>
 
# <code>unzip</code>
   
 
'''To install all of these packages in one fell swoop''' run the command ('''obviously you want to use cut and paste''')
 
'''To install all of these packages in one fell swoop''' run the command ('''obviously you want to use cut and paste''')
   
$ sudo apt install cpanminus curl dvipng dvisvgm gcc git imagemagick libarchive-zip-perl \
+
$ sudo apt install cm-super cpanminus curl dvipng dvisvgm gcc git imagemagick \
libarray-utils-perl libcrypt-ssleay-perl libdata-dump-perl libdata-structure-util-perl \
+
libarchive-zip-perl libarray-utils-perl libclass-tiny-antlers-perl \
libdatetime-perl libemail-address-xs-perl libemail-sender-perl libemail-stuffer-perl \
+
libcrypt-jwt-perl libcryptx-perl libdata-dump-perl libdata-structure-util-perl \
libexception-class-perl libextutils-xsbuilder-perl libfile-find-rule-perl-perl \
+
libdatetime-perl libemail-stuffer-perl libexception-class-perl \
libfile-sharedir-install-perl libfuture-asyncawait-perl libgd-perl libhttp-async-perl \
+
libfile-find-rule-perl libfile-sharedir-install-perl libfuture-asyncawait-perl \
libiterator-perl libiterator-util-perl libjson-perl liblocale-maketext-lexicon-perl \
+
libgd-perl libhttp-async-perl libiterator-perl libiterator-util-perl \
libmime-tools-perl libmojolicious-perl libnet-ip-perl libnet-ldap-perl libnet-oauth-perl \
+
libjson-maybexs-perl libjson-perl liblocale-maketext-lexicon-perl \
libossp-uuid-perl libpath-class-perl libphp-serialization-perl libpod-wsdl-perl libsoap-lite-perl \
+
libmath-random-secure-perl libminion-perl libminion-backend-sqlite-perl \
libsql-abstract-classic-perl libsql-abstract-perl libstring-shellquote-perl libsvg-perl \
+
libmojolicious-perl libmojolicious-plugin-renderfile-perl libnet-ip-perl \
libtemplate-perl libtest-exception-perl libtest-fatal-perl libtest-mockobject-perl \
+
libnet-ldap-perl libnet-oauth-perl libossp-uuid-perl libpadwalker-perl \
libtest-requires-perl libtest-warn-perl libtext-csv-perl libtimedate-perl libtype-tiny-perl \
+
libpandoc-wrapper-perl libpath-class-perl libphp-serialization-perl \
libuniversal-can-perl libuniversal-isa-perl libuuid-tiny-perl libxml-parser-easytree-perl \
+
libpod-wsdl-perl libsoap-lite-perl libsql-abstract-classic-perl \
libxml-parser-perl libxml-writer-perl libyaml-libyaml-perl make netpbm npm openssh-server pdf2svg \
+
libstring-shellquote-perl libsvg-perl libtemplate-perl libtext-csv-perl \
preview-latex-style texlive texlive-latex-extra unzip
+
libtimedate-perl libuniversal-can-perl libuniversal-isa-perl libuuid-tiny-perl \
  +
libxml-parser-easytree-perl libxml-parser-perl libxml-writer-perl \
  +
libyaml-libyaml-perl make netpbm openssh-server pdf2svg preview-latex-style \
  +
texlive texlive-latex-extra texlive-science unzip
   
 
Accept any prompts with the default answer by hitting <code>&lt;Enter&gt;</code>. Restart all services if requested.
 
Accept any prompts with the default answer by hitting <code>&lt;Enter&gt;</code>. Restart all services if requested.
Line 156: Line 175:
 
=== Installation of Other Perl Modules with cpanm ===
 
=== Installation of Other Perl Modules with cpanm ===
   
We will use <code>cpanm</code> to install other perl modules that are not available as Ubuntu packages. The only modules that should need to be installed in this way are <code>Statistics::R::IO</code> and <code>Mojolicious::Plugin::NotYAMLConfig</code>. To install these execute
+
We will use <code>cpanm</code> to install other Perl modules that are not available as Ubuntu packages or a different version than the Ubuntu packaged version is needed. To install these modules execute
   
$ sudo cpanm Statistics::R::IO Mojolicious::Plugin::NotYAMLConfig
+
$ sudo cpanm --notest Statistics::R::IO Perl::Tidy@20220613 XML::LibXML
   
Later we will check that all perl modules have been properly installed.
 
  +
Note that <code>--notest</code> is added to avoid the unit tests that make the installation take considerably longer, and require the installation of additional dependencies used only for the tests.
   
== Installing a Database ==
 
  +
Later we will check that all Perl modules have been properly installed.
  +
  +
== Install a Database ==
   
 
This section installs MariaDB as the database manger for webwork. MariaDB is the recommended database but you can install and use MySQL if you wish.
 
This section installs MariaDB as the database manger for webwork. MariaDB is the recommended database but you can install and use MySQL if you wish.
   
=== Installing and Testing MariaDB ===
+
=== Install and Testing MariaDB ===
   
 
Install MariaDB using the distribution and cpan packages.
 
Install MariaDB using the distribution and cpan packages.
   
$ sudo apt install mariadb-server libmariadb3 libmariadb-dev
+
$ sudo apt install mariadb-server libmariadb3 libmariadb-dev libdevel-checklib-perl
 
$ sudo cpanm DBD::MariaDB
 
$ sudo cpanm DBD::MariaDB
 
Restart all services if requested.
 
Restart all services if requested.
   
=== Securing the Database ===
+
=== Secure the Database ===
   
Then we should secure the server. Note that if you install MariaDB as we suggest, all mysql commands automatically use the MariaDB.
+
Then we should secure the database. Note that if you install MariaDB as suggested, all mysql commands automatically use MariaDB.
   
 
$ sudo mysql_secure_installation
 
$ sudo mysql_secure_installation
Line 204: Line 225:
 
$
 
$
   
==Installing WeBWorK==
 
  +
=== Starting and Stopping MariaDB (or MySQL) ===
  +
  +
On rare occasions you may need to start, stop, or restart the database server.
  +
  +
To start the <code>MariaDB</code> or <code>MySQL</code> server run the command
  +
$ sudo systemctl start mysql
  +
  +
To stop the <code>MariaDB</code> or <code>MySQL</code> server run the command
  +
$ sudo systemctl stop mysql
  +
  +
To restart the <code>MariaDB</code> or <code>MySQL</code> server run the command
  +
$ sudo systemctl restart mysql
  +
  +
To obtain more information about the <code>MariaDB</code> or <code>MySQL</code> server run
  +
$ systemctl status mysql
  +
  +
=== Connection Limits ===
  +
  +
Those coming from earlier versions of WeBWorK, especially 2.13 and 2.14, may have never run into connection limits on the SQL database write, depending on the total class enrollments. In 2.18, especially using hypnotoad (see below), the connection limit default of 151 connections can be reached fairly easily. So long as your system resources allow it, increasing this limit to approximately twice the number of workers used in the web serving can help prevent very scary errors from confusing your users. Edit the MariaDB conf file at:
  +
  +
$ sudo nano /etc/my.cnf
  +
  +
Beneath the first line, which should state something like:
  +
  +
[mysqld]
  +
  +
add a line to increase this number. For example, if the number of workers for your hypnotoad setup (below) was set to 250, then 500 might be an appropriate choice for the maximum number of connections.
  +
  +
Max_connections = [preferred new max digits]
  +
  +
(Aside) If you are using MySQL instead of MariaDB, this file is located at /etc/mysql/mysql.conf.d/mysql.cnf. Same setting, same information, just a different configuration location.
  +
  +
==Install WeBWorK==
 
We are at the point where we can start downloading and installing WeBWorK.
 
We are at the point where we can start downloading and installing WeBWorK.
   
'''Note the instructions below assume you are installing WeBWorK from scratch. If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Upgrading_WeBWorK_from_2.17_to_2.18]].'''
+
'''Note the instructions below assume you are installing WeBWorK from scratch. If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Release notes for WeBWorK 2.18#Upgrade Instructions]].'''
   
 
=== Create the Required Directories ===
 
=== Create the Required Directories ===
Line 215: Line 268:
 
$ cd /opt/webwork
 
$ cd /opt/webwork
 
$ mkdir libraries courses
 
$ mkdir libraries courses
  +
  +
Reminder: You should use the account you selected to administer webwork instead of <code>wwadmin</code> above.
   
 
=== Download the WeBWorK System Software and Problem Libraries ===
 
=== Download the WeBWorK System Software and Problem Libraries ===
 
We will use Git to download WeBWorK from Github. This is easy and it will also make it easy to update the system in the future. Note that for long commands it is much easier to copy (^C) them from this document and paste (<Shift><Ctrl><V> or <Shift><Insert>) them in a terminal window.
 
We will use Git to download WeBWorK from Github. This is easy and it will also make it easy to update the system in the future. Note that for long commands it is much easier to copy (^C) them from this document and paste (<Shift><Ctrl><V> or <Shift><Insert>) them in a terminal window.
   
  +
$ cd /opt/webwork
 
$ git clone https://github.com/openwebwork/webwork2.git
 
$ git clone https://github.com/openwebwork/webwork2.git
 
$ git clone https://github.com/openwebwork/pg.git
 
$ git clone https://github.com/openwebwork/pg.git
Line 246: Line 302:
 
The PG installation directory and files should be owned by the primary <code>wwadmin</code> user and not writable by other users, but readable by all:
 
The PG installation directory and files should be owned by the primary <code>wwadmin</code> user and not writable by other users, but readable by all:
   
$ sudo chmod -R u+rw,go+r /opt/webwork/pg
+
$ sudo chmod -R u+rwX,go+rX /opt/webwork/pg
   
 
Most WeBWorK directories and files should also be owned by the primary <code>wwadmin</code> user and not writable by other users, and again readable by all:
 
Most WeBWorK directories and files should also be owned by the primary <code>wwadmin</code> user and not writable by other users, and again readable by all:
   
$ sudo chmod -R u+rw,go+r /opt/webwork/webwork2
+
$ sudo chmod -R u+rwX,go+rX /opt/webwork/webwork2
   
 
Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. 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. We will use the default group for web services <code>www-data</code>.
 
Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. 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. We will use the default group for web services <code>www-data</code>.
Line 270: Line 326:
 
$ sudo chmod -R g+w DATA ../courses htdocs/tmp logs tmp
 
$ sudo chmod -R g+w DATA ../courses htdocs/tmp logs tmp
   
== Configuring the Shell ==
+
== Configure the Shell ==
   
 
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.
 
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.
Line 298: Line 354:
 
$ echo $PG_ROOT
 
$ echo $PG_ROOT
   
== Install node and npm ==
 
  +
== Obtain Javascript Libraries ==
  +
  +
=== Install node and npm ===
 
WW 2.18 requires newer versions of node and npm than are in the Ubuntu repositories.
 
WW 2.18 requires newer versions of node and npm than are in the Ubuntu repositories.
   
 
Note that if you have a previous version of node installed, then you will need to first uninstall it. To determine if this is the case run
 
Note that if you have a previous version of node installed, then you will need to first uninstall it. To determine if this is the case run
 
$ node --version
 
$ node --version
If that shows <code>v16.??.?</code> then you already have node 16 installed. If that says <code>Command 'none' not found, ...</code>, then skip to installing node below. If a version is shown that does not start with 16, then uninstall node with the commands:
+
If that shows <code>vNN.??.?</code> where <code>NN</code> is 16 or more, then you already have a new enough version of node installed. If that says <code>Command 'node' not found, ...</code>, then skip to installing node below. If a version is shown that does not start with 16 or more, then uninstall node with the commands:
 
$ sudo apt autoremove nodejs nodejs-doc
 
$ sudo apt autoremove nodejs nodejs-doc
 
$ sudo rm /etc/apt/sources.list.d/nodesource.list
 
$ sudo rm /etc/apt/sources.list.d/nodesource.list
Line 313: Line 371:
 
$ sudo apt install -y nodejs
 
$ sudo apt install -y nodejs
   
== Checking Module Dependencies ==
 
  +
=== Installing Javascript Libraries ===
   
WeBWorK includes a script called <code>check_modules.pl</code> (in the directory <code>/opt/webwork/webwork2/bin</code>) that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.
 
  +
Javascript libraries are obtained using <code>npm</code>. This includes the following javascript packages:
 
$ check_modules.pl
 
 
Scroll up and look through the listing. It should find everything. If something is missing (flagged by <code>**</code>), look back through these instructions to find where it should have been installed and install it.
 
 
=== Obtaining Javascript Libraries ===
 
 
Javascript libraries are now obtained using <code>npm</code>. This includes the following javascript packages:
 
   
 
# <code>codemirror</code>
 
# <code>codemirror</code>
Line 342: Line 392:
   
 
$ cd /opt/webwork/webwork2/htdocs/
 
$ cd /opt/webwork/webwork2/htdocs/
$ npm install
+
$ npm ci
 
$ cd /opt/webwork/pg/htdocs/
 
$ cd /opt/webwork/pg/htdocs/
$ npm install
+
$ npm ci
   
Optionally, if you do not wish to serve third party javascript libraries, you may instead choose to have the files served from a CDN. To make this happen instead use:
 
  +
Note that a message may be displayed stating that "Browserlist: caniuse-lite is outdated." You can safely ignore that message.
   
$ cd /opt/webwork/webwork2/htdocs/
 
  +
== Miscellaneous System Patches ==
$ USE_CDN=1 npm install
 
$ cd /opt/webwork/pg/htdocs/
 
$ USE_CDN=1 npm install
 
 
=== Checking LaTeX packages ===
 
 
Now we check that all necessary LaTeX packages have been installed. Run the command
 
$ check_latex
 
and look for missing packages (you can ignore "No file check_latex.aux.").
 
If the script displays "Compilation Success!", then all is good!
 
 
=== Miscellaneous System Patches ===
 
   
 
If the users of your system will be using problems that utilize the new <code>PGtikz.pl</code> macro then you will need to apply the following patch:
 
If the users of your system will be using problems that utilize the new <code>PGtikz.pl</code> macro then you will need to apply the following patch:
Line 366: Line 404:
 
$ sudo patch -p1 -d / < /opt/webwork/webwork2/docker-config/imagemagick-allow-pdf-read.patch
 
$ sudo patch -p1 -d / < /opt/webwork/webwork2/docker-config/imagemagick-allow-pdf-read.patch
   
== Configuring WeBWorK ==
+
== Configure WeBWorK ==
   
=== Making Copies of the Distribution Configuration Files ===
+
=== Make Copies of the Distribution Configuration Files ===
   
 
Before configuring the system, you must make local copies of the <code>site.conf</code> and <code>localOverrides.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code> .
 
Before configuring the system, you must make local copies of the <code>site.conf</code> and <code>localOverrides.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code> .
Line 392: Line 430:
 
$ nano /opt/webwork/webwork2/conf/site.conf
 
$ nano /opt/webwork/webwork2/conf/site.conf
   
First we have to add information about the Apache2 server setup.
+
First we have to add information about your site's URL.
 
Search for <code>server_root_url</code> and edit the line so that it reads:
 
Search for <code>server_root_url</code> and edit the line so that it reads:
   
Line 399: Line 437:
 
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately. The "http://" is important. '''If you are running a secure server (i.e., using SSL - really TLS), the url should start with https:
 
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately. The "http://" is important. '''If you are running a secure server (i.e., using SSL - really TLS), the url should start with https:
 
but you should wait to make that change until after WeBWorK is up and running and you set up SSL. In that case the "https://" is important.
 
but you should wait to make that change until after WeBWorK is up and running and you set up SSL. In that case the "https://" is important.
  +
  +
If you would like to serve third party javascript and css files from a CDN instead of from your server, then change <code>$options{thirdPartyAssetsUseCDN} = 0;</code> to <code>$options{thirdPartyAssetsUseCDN} = 1;</code>.
   
 
==== Database Settings ====
 
==== Database Settings ====
Line 411: Line 451:
 
where of course you should replace "database_password" with your own password but do use the single quotes. '''Remember this password as we will need it below'''.
 
where of course you should replace "database_password" with your own password but do use the single quotes. '''Remember this password as we will need it below'''.
   
WeBWorK sends mail in three instances. The PG system sends mail to report answers to questionnaires and free-response problems. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.
+
WeBWorK sends mail in two instances. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.
   
 
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines
 
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines
Line 426: Line 466:
   
 
Then save the file and Quit.
 
Then save the file and Quit.
  +
  +
==== The defaults.config file ====
  +
  +
The <code>defaults.config</code> contains basic defaults for your system. You should not need to change these but if you decide to, you should not change them here since this file will be overwritten when you update WeBWorK. Instead make the change in the <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.
   
 
==== Custom Themes ====
 
==== Custom Themes ====
Line 434: Line 478:
 
After you have used WeBWorK for awhile, you may want to change the default header files in <code>defaults.config</code>. Search for <code>$webworkFiles{screenSnippets}{setHeader}</code> and <code>$webworkFiles{hardcopySnippets}{setHeader}</code> in <code>localOverrides.config</code>. Settings in the conf and config files affect all WeBWorK courses. You can override any setting in these conf and config files for an individual course by putting the local setting in <code>course.conf</code>.
 
After you have used WeBWorK for awhile, you may want to change the default header files in <code>defaults.config</code>. Search for <code>$webworkFiles{screenSnippets}{setHeader}</code> and <code>$webworkFiles{hardcopySnippets}{setHeader}</code> in <code>localOverrides.config</code>. Settings in the conf and config files affect all WeBWorK courses. You can override any setting in these conf and config files for an individual course by putting the local setting in <code>course.conf</code>.
   
=== Set up the webwork database ===
 
  +
== Check Dependencies ==
  +
  +
=== Check Perl Modules ===
  +
  +
WeBWorK includes a script called <code>check_modules.pl</code> (in the directory <code>/opt/webwork/webwork2/bin</code>) that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.
  +
  +
$ check_modules.pl
  +
  +
Scroll up and look through the listing. It should find everything. If something is missing (flagged by <code>**</code>), look back through these instructions to find where it should have been installed and install it.
  +
  +
=== Check LaTeX packages ===
  +
  +
Now we check that all necessary LaTeX packages have been installed. Run the command
  +
$ check_latex
  +
and look for missing packages.
  +
If the script displays "Compilation Success!", then all is good!
  +
  +
== Set up the webwork database ==
   
 
WeBWorK uses a single database, called <code>webwork</code>, for all courses. We will create the <code>webwork</code> database now.
 
WeBWorK uses a single database, called <code>webwork</code>, for all courses. We will create the <code>webwork</code> database now.
   
To do this do the following ('''before you just copy, paste and hit <code>&lt;Enter&gt;</code>''' notice that you have to replace <code>database_password</code> with the password you set when editing <code>site.conf</code> above):
+
To do this do the following (before you just copy, paste and hit <code>&lt;Enter&gt;</code> make sure that you replace <code>database_password</code> with the password you set when editing <code>site.conf</code> above):
   
 
$ sudo mysql
 
$ sudo mysql
[sudo] password for wwadmin: <wwadmin password>
 
 
 
MariaDB > CREATE DATABASE webwork;
 
MariaDB > CREATE DATABASE webwork;
 
MariaDB > CREATE USER 'webworkWrite'@'localhost' IDENTIFIED BY 'database_password';
 
MariaDB > CREATE USER 'webworkWrite'@'localhost' IDENTIFIED BY 'database_password';
Line 448: Line 507:
 
MariaDB > exit
 
MariaDB > exit
 
Bye
 
Bye
$
+
$
 
where as we said '''replace''' <code>database_password</code> with the password you set when editing <code>site.conf</code> above.
 
   
 
== Serving the Webwork2 Mojolicious App ==
 
== Serving the Webwork2 Mojolicious App ==
   
You now have a choice to make. That is how do you want to serve webwork2. There are two primary choices. Either the app may be served directly via hypnotoad, or it may be proxied via another web server. If your server is dedicated to serving only webwork2, then serving directly via hypnotoad is the simplest choice. However, if your server will be serving other sites as well then you will need to proxy the app via another web server. For that we provide instructions for serving via apache2 or nginx. However, another server could be used as well.
+
You now have a choice to make. That is how to serve webwork2. There are two primary choices. Either the app may be served directly via hypnotoad (option 1 below), or it may be proxied via another web server. If your server is dedicated to serving only webwork2, then serving directly via hypnotoad is the simplest choice. (Note that this option '''does''' allow for either a customizable root url or a redirect of the root url to another site.) However, if your server will be serving other sites as well then you will need to proxy the app via another web server. For that we provide instructions for serving via apache2 or nginx (options 2 and 3 below). However, another server could be used as well.
   
 
All approaches use the webwork2.mojolicious.yml and webwork2.service files. Start by copying the dist files.
 
All approaches use the webwork2.mojolicious.yml and webwork2.service files. Start by copying the dist files.
Line 462: Line 521:
 
Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. Near the beginning of the file change the <code>secrets:</code> to whatever you want to change it to, but don't leave it at the default setting. You can choose random characters or a long phrase.
 
Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. Near the beginning of the file change the <code>secrets:</code> to whatever you want to change it to, but don't leave it at the default setting. You can choose random characters or a long phrase.
   
=== Option 1: Serving directly via hypnotoad ===
+
=== Option 1: Serving Directly via Hypnotoad ===
 
Determine if you are going to be serving securely with ssl certificates or not. If so use port 443 below, otherwise user port 80.
 
   
 
Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. At the very end of the <code>hypnotoad:</code> section comment out the line that reads <code>proxy: 1</code> by inserting a <code>#</code> character at the beginning of the line.
 
Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. At the very end of the <code>hypnotoad:</code> section comment out the line that reads <code>proxy: 1</code> by inserting a <code>#</code> character at the beginning of the line.
   
If you are serving securely with ssl certificates, then change <code>listen:</code> at the beginning of the <code>hypnotoad:</code> section to include your ssl certificates. See the examples in the file for the format that is needed. You will also need to make sure that the www-data user has read permissions for the certificate files.
 
  +
Determine if you are going to be serving securely with SSL certificates or not. If so use port 443 below, otherwise use port 80.
   
By default on Ubuntu ports 80 and 443 can not be bound to by non-root users. The <code>authbind</code> program allows this to be done. Install and configure it with
 
  +
If you are serving securely with SSL certificates, then change <code>listen:</code> at the beginning of the <code>hypnotoad:</code> section to include your ssl certificates. See the examples in the file for the format that is needed. You will also need to make sure that the www-data user has read permissions for the certificate files. This is possibly trickier than you might think: you need the directory path that the certificate and key are in (e.g., .pem files from letsencrypt) to be readable by www-data or whatever your .yml file specifies as the user and group. There is a log by default at /opt/webwork/webwork2/logs/webwork2.log which can often help debugging this step.
   
$ sudo apt insall authbind
 
  +
If you are not serving securely with SSL certificates, then change <code>listen:</code> at the beginning of the <code>hypnotoad:</code> section to <code>- <nowiki>http://*:80</nowiki></code>.
$ sudo touch /etc/autobind/byport/443
 
$ sudo chown www-data /etc/autobind/byport/443
 
$ sudo chmod 500 /etc/autobind/byport/443
 
   
Make sure to change 443 in the commands to 80 if you are not serving securely with ssl certificates.
 
  +
Search for the lines
  +
clients: 1
  +
workers: 25
  +
spare: 8
  +
and edit the numbers depending on the amount of RAM available on your server. Look at the recommendations for these settings in the section immediately above these lines in the webwork2.mojolicious.yml file - roughly 10 workers per GB of RAM, with buffer for the OS and the spare; and spare set to approximately 10% of total workers.
  +
  +
Then save the file and Quit.
  +
  +
==== Install Mojolicious::Plugin::SetUserGroup ====
  +
  +
By default on Ubuntu ports 80 and 443 can not be bound to by non-root users, and so the hypnotoad server will be started as root so that the needed ports can be bound. However, the server should not be run as root as that is a security vulnerability. So the server will be switched to the www-data user after the ports have been bound. The <code>Mojolicious::Plugin::SetUserGroup</code> module takes care of this. Install it with
  +
  +
$ sudo cpanm --notest Mojolicious::Plugin::SetUserGroup
  +
  +
The <code>--notest</code> flag is needed to skip the module unit tests on Ubuntu 22.04 as those tests fail.
  +
  +
==== Configure the Webwork2 Systemd Service ====
   
Next set up the systemd service that will control the webwork2 app. Edit /opt/webwork/webwork2/conf/webwork2.service with your preferred text editor. Comment out the line that reads
+
There are a few changes to the systemd service configuration needed for this option. Edit /opt/webwork/webwork2/conf/webwork2.service with your preferred text editor. Comment out the lines that read
  +
User=www-data
  +
Group=www-data
 
Environment="MOJO_REVERSE_PROXY=1"
 
Environment="MOJO_REVERSE_PROXY=1"
by inserting a <code>#</code> character at the beginning of the line. Change the line that reads
+
by inserting a <code>#</code> character at the beginning of each line.
ExecStart=hypnotoad /opt/webwork/webwork2/bin/webwork2
 
to
 
ExecStart=authbind --deep hypnotoad /opt/webwork/webwork2/bin/webwork2
 
Then execute the following to enable and start the service.
 
$ sudo systemctl enable /opt/webwork/webwork2/conf/webwork2.service
 
$ sudo systemclt start webwork2
 
   
At this point webwork2 is now running, and you should be able to open your browser to <nowiki>http://yoursite.edu/webwork2</nowiki> (if you used port 80 above) or <nowiki>https://yoursite.edu/webwork2</nowiki> (if you used port 443 above). Skip options 2 and 3 below to continue setting up courses.
 
  +
Then save the file and Quit.
  +
  +
==== Optional Configuration Details ====
  +
  +
Next determine where you want the root url to go, i.e., the location <nowiki>http[s]://yoursite.edu/</nowiki>.
  +
  +
If you want to display fixed html content, then execute
  +
$ cp /opt/webwork/webwork2/htdocs/index.dist.html /opt/webwork/webwork2/htdocs/index.html
  +
and edit the copied file by adding your custom content.
  +
  +
If you want to redirect to another site, then edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml, uncomment the <code>server_root_url_redirect:</code> setting, and change that setting to point to the desired site.
  +
  +
If you are serving securely with SSL certificates, then you will most likely want to redirect unsecure connections to port 80 to secure connections on port 443. To make this happen add the line <code>- <nowiki>http://*:80</nowiki></code> below the line <code>- <nowiki>https://*:443?...</nowiki></code> in the <code>listen:</code> part of the the <code>hypnotoad:</code> section, and change <code>redirect_http_to_https: 0</code> to <code>redirect_http_to_https: 1</code> in the file /opt/webwork/webwork2/conf/webwork2.mojolicious.yml.
   
 
=== Option 2: Serving via Proxy by Apache2 ===
 
=== Option 2: Serving via Proxy by Apache2 ===
   
This sets up some helpful modules for apache and tests to make sure that apache is up and running. These modules are useful but not necessary.
 
  +
First install the apache2 server with
   
=== enabling info.conf and status.conf in Ubuntu ===
 
  +
$ sudo apt install apache2
   
We enable the info module. Acting as <code>root</code> in a terminal window enter
 
  +
Note that this guide does not cover basic site configuration of the apache2 server.
$ sudo a2enmod info
 
   
Next we make a copy of the configuration files we will be editing for safekeeping.
 
  +
Webwork2 ships with an apache2 configuration file that needs to linked into your apache2 configuration process. Create a copy of the dist file with
 
$ cd /etc/apache2/mods-available
 
   
$ sudo cp info.conf info.conf.bak1
 
  +
$ cp /opt/webwork/webwork2/conf/webwork2.apache2.4.dist.conf /opt/webwork/webwork2/conf/webwork2.apache2.4.conf
$ sudo cp status.conf status.conf.bak1
 
   
Now we will edit configuration files <code>info.conf</code> and <code>status.conf</code> to allow us to view information about the setup and performance of the web server. Note that this is not absolutely necessary but it can be very useful. You can use your favorite editor but we will give instructions assuming you are using <code>nano</code>. Note that you have to be root to edit these files. First we edit <code>info.conf</code>
 
  +
and link it into your apache2 configuration process with
   
$ cd /etc/apache2/mods-available
 
  +
$ sudo ln -s /opt/webwork/webwork2/conf/webwork2.apache2.4.conf /etc/apache2/conf-enabled/webwork2.conf
$ sudo nano info.conf
 
   
I suggest you allow access to server information from e.g. your department domain. To do this un-comment (i.e. remove the <code>#</code> from)
 
  +
If you do not have ssl certificates to serve with https, then edit /opt/webwork/webwork2/webwork2.apache2.4.conf, and change <code>RequestHeader set X-Forwarded-Proto "https"</code> to <code>RequestHeader set X-Forwarded-Proto "http"</code>.
Require ip 192.0.2.0/24
 
and then replace <code>Require ip 192.0.2.0/24</code> by <code>Require host math.yourschool.edu</code> (or <code>Require host yourschool.edu</code> if you want to allow wider access)
 
where of course you should edit <code>math.yourschool.edu</code> appropriately. You could also use a specific or range of ip addresses
 
following the syntax in the example.
 
   
  +
Additional apache2 modules are needed to proxy webwork2. Enable these with
   
Then save the file and quit (press <code>^X</code>, <code>Y</code>, <code>&lt;Enter&gt;</code>).
 
  +
$ sudo a2enmod proxy proxy_http headers
   
Now we edit <code>status.conf</code>
 
  +
Next we will make a few changes to Apache's default configuration. We need to edit two files. First we will
  +
save copies of the original files.
   
$ cd /etc/apache2/mods-available
+
$ cd /etc/apache2/
$ sudo nano status.conf
+
$ sudo cp apache2.conf apache2.conf.bak
  +
$ cd /etc/apache2/mods-available/
  +
$ sudo cp mpm_event.conf mpm_event.conf.bak
   
Edit the
 
  +
==== Edit apache2.conf ====
#Require ip 192.0.2.0/24
 
line just as you did for <code>info.conf</code>.
 
Then save the file and quit. And restart Apache so that the above changes take effect
 
   
$ sudo systemctl restart apache2
+
$ sudo nano /etc/apache2/apache2.conf
   
===Fully Qualified Domain Name===
 
  +
Search for the line
Now we have to set your server's fully qualified domain name. Note that if your network was set up automatically via DHCP, your server's fully qualified domain name should already be set up. You can check by running the <code>hostname</code> commands below.
 
  +
Timeout 300
  +
and replace it by
  +
Timeout 1200
   
Run the command
 
  +
Then save the file and quit.
sudo hostnamectl set-hostname webwork
 
where of course you should replace webwork by whatever your server's name is.
 
   
You can check these settings by running the commands
 
  +
==== Edit mpm_event.conf ====
   
$ hostname --fqdn
 
  +
$ sudo nano /etc/apache2/mods-available/mpm_event.conf
and
 
$ hostname
 
   
The first gives the server's fully qualified domain name (e.g. webwork.mydepartment.myschool.edu) and the second the server's name (e.g. webwork).
 
  +
Search for the lines
  +
MaxRequestWorkers 150
  +
MaxConnectionsPerChild 0
  +
Which occur under <code><IfModule mpm_event_module></code> and replace them by
  +
MaxRequestWorkers 10
  +
MaxConnectionsPerChild 50
  +
where you should set MaxRequestWorkers depending on what is needed for your server. A good rule of thumb is 5 MaxRequestWorkers per 1 GB of memory available on the server. Note that for busy servers, you should observe your memory usage and adjust the above settings as necessary. Also make sure MaxSpareThreads is not set too high.
   
Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) may not start.
 
  +
Then save the file and quit.
   
===Test Apache===
 
  +
Now restart apache2 so that changes to the configuration take effect.
Now restart Apache
 
   
 
$ sudo systemctl restart apache2
 
$ sudo systemctl restart apache2
   
and test your server by connecting to your server ("<nowiki>http://yourserver.yourschool.edu</nowiki>") from a browser on a remote machine. You should see the '''Apache2 Ubuntu Default Page''' indicating that Apache is running.
 
  +
The apache2 process is controlled with <code>systemctl</code>. If the apache2 configuration is changed, then you will need to restart apache2 in order for those changes to take effect as was done above. In addition you can stop and start the apache2 process with
  +
$ sudo systemctl stop apache2
  +
$ sudo systemctl start apache2
  +
You can also obtain more information about the running service with
  +
$ systemctl status apache2
   
You can check Apache's status by connecting to "<nowiki>http://yourserver.yourschool.edu/server-status</nowiki>" from a browser on a remote machine in the math.yourschool.edu domain.
 
  +
Sometimes to determine problems with the apache2 process it is helpful to view the apache2 error log. The log is saved in the file /var/log/apache2/error.log.
   
Further test Apache by connecting to "<nowiki>http://yourserver.yourschool.edu/server-info</nowiki>" from a browser on a remote machine in the math.yourschool.edu domain and you will see a page listing various information about Apache. In particular under <code>Server Settings</code> you should see
 
  +
=== Option 3: Serving via Proxy by Nginx ===
Server Version: Apache/2.4.52 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.12 Perl/v5.34.0
 
(or something very similar) indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed.
 
   
If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>. In the directory <code>/var/log/apache2/</code> you can "less" through the error log (<code>less error.log</code>), look at the last few entries (<code>tail error.log</code>) or run the command <code>tail -f error.log</code> which will display new error messages as they are appended to the file. To quit less and go back to the command line press q and use
 
  +
First install the Nginx server with
<code>^C</code> to break out of <code>tail -f</code> . For example if you didn't set up access to "server-info", you can run
 
$ tail /var/log/apache2/error.log
 
and in the output you should see something similar to
 
...[mpm_event:notice] [pid 35885:tid 139917041878912] AH00489: Apache/2.4.52 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.12 Perl/v5.34.0 configured -- resuming normal operations
 
   
indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed and running.
 
  +
$ sudo apt install nginx
   
=== Configuring Apache ===
 
  +
At this point this guide does not cover basic site configuration. Ubuntu has a default configuration file located at <code>/etc/nginx/sites-available/default</code> that you can start with for this. (Nginx documentation recommends using a file in <code>/etc/nginx/conf.d</code> instead.) In any case make note of which file you are using for the following. This will be referred to as "your site's Nginx configuration file."
WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named <code>webwork.apache2.4-config.dist</code> and located in the <code>conf</code> directory. First, copy the file to <code>webwork.apache2-config</code>:
 
   
$ cd /opt/webwork/webwork2/conf
 
  +
Webwork2 ships with an Nginx configuration file that needs to be included in your Nginx configuration. Create a copy of the dist file with
$ cp webwork.apache2.4-config.dist webwork.apache2.4-config
 
   
and now link it into your Apache configuration process
 
  +
$ cp /opt/webwork/webwork2/conf/webwork2.nginx.dist.conf /opt/webwork/webwork2/conf/webwork2.nginx.conf
   
$ sudo ln -s /opt/webwork/webwork2/conf/webwork.apache2.4-config /etc/apache2/conf-enabled/webwork.conf
 
  +
Edit your site's Nginx configuration file to include this file. In your configuration file find the primary <code>server</code> section, and add the line <code>include /opt/webwork/webwork2/conf/webwork2.nginx.conf;</code> to the end of the section. You will need to determine which <code>server</code> section is the correct one to use if you have multiple such sections in the file.
   
The default multi-processing module (MPM) for Apache is the event module but WeBWorK uses the prefork module. So we disable the event module and enable the prefork module.
 
  +
Restart the nginx process for that change to take effect.
   
$ sudo a2dismod mpm_event
+
$ sudo systemctl restart nginx
$ sudo a2enmod mpm_prefork
 
   
WeBWorK requires the Apache 2 rewrite module to be enabled for serving files in the pg/htdocs location.
 
  +
The nginx process is controlled with <code>systemctl</code>. If the nginx configuration is changed, then you will need to restart nginx as done above. In addition you can stop and start the nginx process with
  +
$ sudo systemctl stop nginx
  +
$ sudo systemctl start nginx
  +
You can also obtain more information about the running service with
  +
$ systemctl status nginx
   
$ sudo a2enmod rewrite
 
  +
Sometimes to determine problems with the nginx process it is helpful to view the nginx error log. The log is saved in the file /var/log/nginx/error.log.
   
Next we will make a few changes to Apache's default configuration. We need to edit two files. First we will
 
  +
=== Install Favicon for Options 2 and 3 ===
save copies of the original files.
 
$ sudo -s
 
# cd /etc/apache2/
 
# cp apache2.conf apache2.conf.bak1
 
# cd /etc/apache2/mods-available/
 
# cp mpm_prefork.conf mpm_prefork.conf.bak1
 
# exit
 
   
====Edit apache2.conf====
 
  +
Copy WeBWorK's icon file <code>favicon.ico</code> to Ubuntu's <code>html</code> directory.
  +
$ sudo cp /opt/webwork/webwork2/htdocs/favicon.ico /var/www/html
   
$ sudo nano /etc/apache2/apache2.conf
 
  +
=== Enable and start the Webwork2 Systemd Service ===
   
Search for the line
 
  +
Next set up the systemd service that will control the webwork2 app. Execute the following to enable and start the service.
Timeout 300
 
  +
$ sudo systemctl enable /opt/webwork/webwork2/conf/webwork2.service
and replace it by
 
  +
$ sudo systemctl start webwork2
Timeout 1200
 
   
Then save the file and quit.
 
  +
At this point webwork2 is now running, and you should be able to open your browser to <nowiki>http://yoursite.edu/webwork2</nowiki> or <nowiki>https://yoursite.edu/webwork2</nowiki>.
   
====Edit mpm_prefork.conf====
 
  +
Note that anytime you make changes to the webwork2 configuration files you will need to restart the app in order for those changes to take effect. This can be done by executing
  +
$ sudo systemctl restart webwork2
  +
In addition you can stop and start the webwork2 app with
  +
$ sudo systemctl stop webwork2
  +
$ sudo systemctl start webwork2
   
$ cd /etc/apache2/mods-available/
 
  +
== Set Up the Webwork2 Job Queue ==
$ sudo nano mpm_prefork.conf
 
   
Search for the lines
 
  +
Some long running processes are not directly run by the webwork2 app. Particularly mass grade updates via LTI and sending of instructor emails. Instead these tasks are executed via the webwork2 Minion job queue. If the users of your system will be utilizing either of those features, then you will need to set up the webwork2 job queue. If those features will not be utilized by the users of your system, then you can skip this section.
MaxRequestWorkers 150
 
MaxConnectionsPerChild 0
 
Which occur under <code><IfModule mpm_prefork_module></code> and replace them by
 
# For WeBWorK a rough rule of thumb is 5 MaxRequestWorkers per 1 GB of memory
 
MaxRequestWorkers 10
 
MaxConnectionsPerChild 50
 
where you should set <code>MaxRequestWorkers</code> depending on the amount of memory your server has using the above rule of thumb. Note that for
 
very busy servers, you should observe you memory usage and adjust the above settings as necessary. Also make sure MaxSpareServers is not set too high.
 
   
Then save the file and quit.
 
  +
=== Install Dependencies ===
   
Finally we copy WeBWorK's icon file <code>favicon.ico</code> to Apache's <code>html</code> directory.
 
  +
The <code>libminion-backend-sqlite-perl</code> package installed above depends on <code>libmojo-sqlite-perl</code> which contains version 3.008 of the Perl module <code>Mojo::SQLite</code>. Unfortunately, there is an issue with that version on Ubuntu 22.04 that prevents the Minion SQLite backend from functioning correctly. So version 3.002 needs to be installed from CPAN instead.
$ sudo cp /opt/webwork/webwork2/htdocs/favicon.ico /var/www/html
 
[sudo] password for wwadmin: <wwadmin password>
 
   
Now stop and start Apache. We do it this way to make sure the MPM gets changed.
 
  +
First install additional Ubuntu packages that are needed for this with
   
$ sudo systemctl stop apache2
 
  +
$ sudo apt install libextutils-config-perl libextutils-installpaths-perl libextutils-helpers-perl
[sudo] password for wwadmin: <wwadmin password>
 
  +
$ sudo systemctl start apache2
 
  +
Then downgrade <code>Mojo::SQLite</code> with the command
  +
  +
$ sudo cpanm --notest Mojo::SQLite@3.002
  +
  +
Note that the <code>--notest</code> flag is needed as the unit tests that are executed by default also fail.
  +
  +
=== Enable and start the Webwork2 Job Queue Systemd Service ===
  +
  +
Copy <code>webwork2-job-queue.dist.service</code> to <code>webwork2-job-queue.service</code> with
  +
$ cd /opt/webwork/webwork2/conf
  +
$ cp webwork2-job-queue.dist.service webwork2-job-queue.service
  +
  +
Then execute the following to start the job queue
  +
  +
$ sudo systemctl enable /opt/webwork/webwork2/conf/webwork2-job-queue.service
  +
$ sudo systemctl start webwork2-job-queue
  +
  +
Note that you can start, stop, and restart the job queue with the following commands:
  +
$ sudo systemctl start webwork2-job-queue
  +
$ sudo systemctl stop webwork2-job-queue
  +
$ sudo systemctl restart webwork2-job-queue
  +
  +
It is worth checking to make sure the webwork2-job-queue has started properly. If anything is wrong, it'll quietly just hang, and then most of the courses will run fine, except certain things like mass grade updates, which will just never run.
  +
  +
$ sudo systemctl status webwork2-job-queue
  +
  +
Even though the <code>webwork2-job-queue.service</code> file specifies user <code>www-data</code> and group <code>www-data</code>, and even if permissions are set appropriately as above (re: logs directory), if you're doing an upgrade-in-place, you might end up in a situation where the <code>www-data</code> user can't write to <code>webwork2.log</code>, and then the job queue will fail. The above status check will indicate this, and you can then double-check permissions on the log directory, and make sure that the files are writeable by <code>www-data</code>.
   
 
== Test your configuration ==
 
== Test your configuration ==
Line 632: Line 721:
 
Test the <code>/webwork2</code> location by visiting <code><nowiki>http://yourserver.yourschool.edu/webwork2</nowiki></code>. You should see the WeBWorK home page with no courses listed. Actually the directory <code>/opt/webwork/courses/</code> does contain the <code>modelCourse</code> but the <code>modelCourse</code> is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason <code>/opt/webwork/courses/modelCourse/</code> contains a file named <code>hide_directory</code> and so the <code>modelCourse</code> is not visible.
 
Test the <code>/webwork2</code> location by visiting <code><nowiki>http://yourserver.yourschool.edu/webwork2</nowiki></code>. You should see the WeBWorK home page with no courses listed. Actually the directory <code>/opt/webwork/courses/</code> does contain the <code>modelCourse</code> but the <code>modelCourse</code> is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason <code>/opt/webwork/courses/modelCourse/</code> contains a file named <code>hide_directory</code> and so the <code>modelCourse</code> is not visible.
   
==If Something is Wrong ==
+
== If Something is Wrong ==
If something is wrong one of the first things to check is that the config files have been edited correctly (e.g. one time a wrapped line in <code>localOverrides.conf</code> caused me problems, another time it was a missing single quote). A quick way to check this is to do a <code>diff</code> between the edited and distributed versions and check that <code>diff</code> reports the changes you made and only those. Another thing is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>.
+
If something is wrong one of the first things to check is that the config files have been edited correctly. A quick way to check this is to do a <code>diff</code> between the edited and distributed versions and check that <code>diff</code> reports the changes you made and only those. You may also want to check the webwork2 app log. Errors and other information from the running app will appear here. The webwork2 app log is saved in the file /opt/webwork/webwork2/logs/webwork2.log.
   
$ cd /etc/apache2/
 
$ diff apache2.conf apache2.conf.bak1
 
 
$ cd /opt/webwork/webwork2/conf/
 
$ cd /opt/webwork/webwork2/conf/
 
$ diff site.conf site.conf.dist
 
$ diff site.conf site.conf.dist
 
$ diff localOverrides.conf localOverrides.conf.dist
 
$ diff localOverrides.conf localOverrides.conf.dist
$ diff webwork.apache2.4-config webwork.apache2.4-config.dist
 
  +
$ tail /opt/webwork/webwork2/logs/webwork2.log
$ tail /var/log/apache2/error.log
 
   
If something is wrong and you fix it, you will have to restart Apache for the changes to take effect
+
If something is wrong and you fix it, you will have to restart webwork2 for the changes to take effect
   
$ sudo systemctl restart apache2
+
$ sudo systemctl restart webwork2
[sudo] password for wwadmin: <wwadmin password>
+
  +
If webwork2 is proxied via another web server, then you may also need to examine the configuration files and log files for the web server as well. If changes are made to the web servers configuration file, then the web server will need to be restarted.
   
 
== Create the admin Course ==
 
== Create the admin Course ==
Line 653: Line 739:
   
 
$ cd /opt/webwork/courses
 
$ cd /opt/webwork/courses
$ /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin
+
$ /opt/webwork/webwork2/bin/addcourse admin --users=adminClasslist.lst
$ sudo chown -R www-data:www-data admin
+
$ sudo chown -R www-data:www-data admin
[sudo] password for wwadmin: <wwadmin password>
 
   
 
where the last line makes the course <code>admin</code> and its subdirectories owned by the Apache server and readable/writeable by the wwadmin user.
 
where the last line makes the course <code>admin</code> and its subdirectories owned by the Apache server and readable/writeable by the wwadmin user.
Line 673: Line 759:
   
 
At some point you will probably want to hide the <code>admin</code> course so that it is not listed on the WeBWorK home page. As we noted above the <code>modelCourse</code>, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The <code>modelCourse</code> is very useful as a model (hence its name) for setting up other courses. The <code>admin</code> course is used for administering WeBWorK and even though regular users can not log into it (you did change the <code>admin</code> password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes.
 
At some point you will probably want to hide the <code>admin</code> course so that it is not listed on the WeBWorK home page. As we noted above the <code>modelCourse</code>, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The <code>modelCourse</code> is very useful as a model (hence its name) for setting up other courses. The <code>admin</code> course is used for administering WeBWorK and even though regular users can not log into it (you did change the <code>admin</code> password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes.
To hide (or unhide) a course select <code>Hide Inactive courses</code> in the admin course and follow the directions. When hidden a course will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the <code>admin</code> course using the URL <code><nowiki>http://yourserver.yourschool.edu/webwork2/admin</nowiki></code> but you will not see a link for it on the WeBWorK home page <code><nowiki>http://yourserver.yourschool.edu/webwork2</nowiki></code> .
+
To hide (or unhide) a course select <code>Hide Courses</code> in the admin course and follow the directions. When hidden a course will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the <code>admin</code> course using the URL <code><nowiki>http://yourserver.yourschool.edu/webwork2/admin</nowiki></code> but you will not see a link for it on the WeBWorK home page <code><nowiki>http://yourserver.yourschool.edu/webwork2</nowiki></code> .
   
   
 
Now go to <code><nowiki>http://yourserver.yourschool.edu/webwork2</nowiki></code> and no course will be listed.
 
Now go to <code><nowiki>http://yourserver.yourschool.edu/webwork2</nowiki></code> and no course will be listed.
   
==Checking for and Installing Hotfixes==
+
== Check for and Install Hotfixes ==
   
The following commands show you how to check for and install bug fixes. '''Important Note:''' These commands check and retrieve the main branch which gives the latest stable release of the software package (webwork2, pg, etc.) with bug fixes. If a stable release newer than 2.16 exists for webwork2 and/or pg, that will be checked and retrieved which is probably not what you want. Please check before updating. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/main/VERSION and https://github.com/openwebwork/pg/blob/main/VERSION.
+
The following commands show you how to check for and install bug fixes. '''Important Note:''' These commands check and retrieve the main branch which gives the latest stable release of the software package (webwork2, pg, etc.) with bug fixes. If a stable release newer than 2.18 exists for webwork2 and/or pg, that will be checked and retrieved which is probably not what you want. Please check before updating. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/main/VERSION and https://github.com/openwebwork/pg/blob/main/VERSION.
   
 
To check if there are bug fixes, do the following.
 
To check if there are bug fixes, do the following.
===Updating the webwork2 code===
+
=== Update the webwork2 code ===
   
 
First we check for updates to the webwork2 code:
 
First we check for updates to the webwork2 code:
Line 689: Line 775:
 
git remote show origin
 
git remote show origin
 
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run
 
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run
git pull origin
+
git pull origin
and restart apache2.
+
and restart webwork2.
   
===Updating the pg code===
+
=== Update the pg code ===
   
 
Now check for updates to the pg code:
 
Now check for updates to the pg code:
Line 699: Line 785:
 
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run
 
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run
 
git pull origin
 
git pull origin
and restart apache2.
+
and restart webwork2.
   
===Restart apache2===
+
=== Restart webwork2 ===
   
'''Important:''' After updating either webwork2 or pg, you have to restart apache2
+
'''Important:''' After updating either webwork2 or pg, you have to restart the webwork2 app with
$ sudo systemctl restart apache2
+
$ sudo systemctl restart webwork2
password:<wwadmin password>
 
   
===Updating the OPL===
+
=== Update the OPL ===
   
 
The following assumes you have already installed the OPL. For that see [[#Install the Open Problem Library]] below.
 
The following assumes you have already installed the OPL. For that see [[#Install the Open Problem Library]] below.
Line 715: Line 801:
 
$ git pull origin
 
$ git pull origin
 
$ OPL-update
 
$ OPL-update
'''Important Note:''' The OPL contains over 37,000 problems and if one new problem is added, the above will report the OPL is out of date. I would suggest you update the OPL maybe once or twice a semester. Also the version of the OPL contained in the WW 2.17 Virtual Machine Image and in the WW 2.17 Amazon Machine Image is current as of August 1, 2022.
+
'''Important Note:''' The OPL contains over 37,000 problems and if one new problem is added, the above will report the OPL is out of date. I would suggest you update the OPL maybe once or twice a semester. Also the version of the OPL contained in the WW 2.18 Virtual Machine Image and in the WW 2.18 Amazon Machine Image is current as of August 1, 2023.
   
Updating the OPL is pretty much risk free since changes usually involve only a relatively small number of individual problems and the vast majority of problems remain unchanged. Updating the OPL does not require restarting apache2.
+
Updating the OPL is pretty much risk free since changes usually involve only a relatively small number of individual problems and the vast majority of problems remain unchanged. Updating the OPL does not require restarting webwork2.
   
== Starting and Stopping Apache and MySQL ==
 
  +
== Install the WeBWorK Problem Libraries ==
If you make changes to the system, you may need to restart <code>apache2</code> in order for the changes take effect. On rare occasions you may need to restart <code>MariaDB</code>. These system services are controlled with <code>systemctl</code>. Most <code>systemctl</code> commands must be run as <code>root</code> via sudo.
 
 
Run
 
$ systemctl --help
 
to obtain a list of all possible commands. The primary commands being <code>start</code>, <code>stop</code>, <code>restart</code> and <code>status</code>.
 
 
=== Starting and Stopping Apache ===
 
 
To restart the <code>apache2</code> web server run the command
 
$ sudo systemctl restart apache2
 
You can also stop <code>apache2</code> with
 
$ sudo systemctl stop apache2
 
and start it with
 
$ sudo systemctl start apache2
 
 
To obtain more information about the <code>apache2</code> server run
 
$ systemctl status apache2
 
 
=== Starting and Stopping MySQL or MariaDB ===
 
 
To start the <code>MariaDB</code> or <code>MySQL</code> server run the command
 
$ sudo systemctl start mysql
 
 
To stop the <code>MariaDB</code> or <code>MySQL</code> server run the command
 
$ sudo systemctl stop mysql
 
 
To restart the <code>MariaDB</code> or <code>MySQL</code> server run the command
 
$ sudo systemctl restart mysql
 
 
To obtain more information about the <code>MariaDB</code> or <code>MySQL</code> server run
 
$ systemctl status mysql
 
 
==Install the WeBWorK Problem Libraries ==
 
 
Before we create a real course we will install the WeBWorK Problem Libraries.
 
Before we create a real course we will install the WeBWorK Problem Libraries.
   
===Install the Open Problem Library ===
+
=== Install the Open Problem Library ===
 
The <code>Open 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 load a database for searching it.
 
The <code>Open 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 load a database for searching it.
   
Run the <code>OPL-update</code> script which will download the OPL metadata release and checkout the corresponding tag in the library as needed for the Library Browser in WeBWorK. Since this is a new installation, we do not have any OPL statistics to upload (see [[OPL_Problem_Statistics]]), so we run the two commands:
+
Run the <code>OPL-update</code> script which will download the OPL metadata release and checkout the corresponding tag in the library as needed for the Library Browser in WeBWorK. Since this is a new installation, we do not have any OPL statistics to upload (see [[OPL_Problem_Statistics]]), so we run the command:
$ export SKIP_UPLOAD_OPL_STATISTICS=1
+
$ SKIP_UPLOAD_OPL_STATISTICS=1 OPL-update
$ OPL-update
 
   
 
If at some time in the future you want to upgrade the Problem Library, the process
 
If at some time in the future you want to upgrade the Problem Library, the process
Line 765: Line 818:
 
new problems and bug fixes for old ones.
 
new problems and bug fixes for old ones.
   
===Set up the access to the Contrib directory ===
+
=== Set up access to the Contrib directory ===
 
The <code>Contrib</code> directory contains contributions to the OPL that may not have been formally accepted into the main collection of OPL problems. This may be because the contribution is recent and has not yet been reviewed or because the problems are not properly tagged as is the case with the CAPA problem collection. It also contains the original versions of problems that have been accepted into the OPL (the idea being that the original authors maintain control of problems in the <code>Contrib</code> directory but problems in the OPL are controled by the editors). This step creates a button in the Library Browser which gives a direct link to the <code>Contrib</code> directory.
 
   
  +
The <code>Contrib</code> directory contains contributions to the OPL that may not have been formally accepted into the main collection of OPL problems. This may be because the contribution is recent and has not yet been reviewed or because the problems are not properly tagged as is the case with the CAPA problem collection. It also contains the original versions of problems that have been accepted into the OPL (the idea being that the original authors maintain control of problems in the <code>Contrib</code> directory but problems in the OPL are controlled by the editors).
   
Put a link to the Contrib directory in the
+
There should be a link named <code>Contrib</code> in the directory
 
/opt/webwork/courses/modelCourse/templates/
 
/opt/webwork/courses/modelCourse/templates/
directory so that when we create courses copying templates from the <code>modelCourse</code>, the Contrib directory will be available. '''Actually this link, called <code>Contrib</code>, has already been added so no action on your part is required'''.
+
so that when courses are created copying templates from the <code>modelCourse</code>, the Contrib directory will be available. A button in the Library Browser which gives access to problems in the <code>Contrib</code> directory will be available for all courses with this link. We recommend you keep this setting.
   
If you just want to do this for individual courses, not all courses then remove the link in the <code>modelCourse</code> above, and then do the following. Note we don't have any individual courses yet. But for example after creating <code>myTestCourse</code> below, to set up access to the <code>Contrib</code> directory from <code>myTestCourse</code>, do the following
+
However, if you only want this for individual courses, not all courses then remove the link in the <code>modelCourse</code> above. Then after creating a course, for example after creating <code>myTestCourse</code> below, do the following
 
$ cd /opt/webwork/courses/myTestCourse/templates/
 
$ cd /opt/webwork/courses/myTestCourse/templates/
$ sudo $ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib Contrib
+
$ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib Contrib
[sudo] password for wwadmin: <wwadmin password>
+
to enable access to Contrib for the course. For other courses change myTestCourse to the course id.
   
===Set up the Rochester and Union Libraries ===
+
=== 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>OPL Directory</code> button. But you can follow this example if you want to create button(s) for direct access to other sub 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>OPL Directory</code> button. But you can follow this example if you want to create button(s) for direct access to other sub libraries.
Line 787: Line 841:
   
 
Search for <code>courseFiles{problibs}</code> and scroll down several lines to the lines
 
Search for <code>courseFiles{problibs}</code> and scroll down several lines to the lines
# rochesterLibrary =&gt; "Rochester",
+
# rochesterLibrary =&gt; "Rochester",
 
# unionLibrary =&gt; "Union",
 
# unionLibrary =&gt; "Union",
 
Uncomment these lines (i.e. remove the <code>#</code>) so they become
 
Uncomment these lines (i.e. remove the <code>#</code>) so they become
Line 797: Line 851:
   
 
$ cd /opt/webwork/courses/modelCourse/templates/
 
$ cd /opt/webwork/courses/modelCourse/templates/
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Union unionLibrary
+
$ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Union unionLibrary
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Rochester rochesterLibrary
+
$ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/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/webwork-open-problem-library/OpenProblemLibrary/</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>
 
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/webwork-open-problem-library/OpenProblemLibrary/</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>
Line 804: Line 858:
 
It's easier to just avoid such names.
 
It's easier to just avoid such names.
   
===Install and Set Up the CAPA Library ===
+
=== 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.
 
This step is optional. It installs and sets up [[CAPA Physics Problems|the CAPA Library]], which is a library of physics problems.
Line 816: Line 870:
 
$ cd /opt/webwork/courses/myTestCourse/templates/
 
$ cd /opt/webwork/courses/myTestCourse/templates/
 
$ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/ capaLibrary
 
$ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/ capaLibrary
[sudo] password for wwadmin: <wwadmin password>
 
   
 
 
and do the analogous thing for every course that needs access to the CAPA Library.
 
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.
 
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 ==
+
== Create Your First Actual Course ==
   
 
Since we have edited <code>site.conf</code> and <code>localOverrides.conf</code> and these are critical files, it would be a good idea to run
 
Since we have edited <code>site.conf</code> and <code>localOverrides.conf</code> and these are critical files, it would be a good idea to run
Line 829: Line 881:
 
$ diff localOverrides.conf localOverrides.conf.dist
 
$ diff localOverrides.conf localOverrides.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 either of these files you must restart the Apache webserver in order for these changes to take effect.
+
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 these files you must restart the webwork2 app in order for these changes to take effect. Do this with
   
Since we have edited <code>global.conf</code> and haven't restarted Apache we do so now.
 
  +
$ sudo systemctl restart webwork2
$ sudo apache2ctl graceful
 
password:<wwadmin password>
 
   
 
Now log into the <code>admin</code> course ( <code><nowiki>http://yourserver.yourschool.edu/webwork2/admin</nowiki></code> or, if you have not hidden the admin course, click on <code>Course Administration</code> on WeBWorK's home page <code><nowiki>http://yourserver.yourschool.edu/webwork2/</nowiki></code> ) as yourself or <code>admin</code> and
 
Now log into the <code>admin</code> course ( <code><nowiki>http://yourserver.yourschool.edu/webwork2/admin</nowiki></code> or, if you have not hidden the admin course, click on <code>Course Administration</code> on WeBWorK's home page <code><nowiki>http://yourserver.yourschool.edu/webwork2/</nowiki></code> ) as yourself or <code>admin</code> and
# click on <code>Add Course</code>
+
# click on <code>Add Courses</code>
 
# For <code>Course ID</code> enter <code>myTestCourse</code>
 
# For <code>Course ID</code> enter <code>myTestCourse</code>
 
# For <code>Course Title</code> enter <code>My Test Course</code>
 
# For <code>Course Title</code> enter <code>My Test Course</code>
 
# Enter your institution
 
# Enter your institution
# Leave <code>Add WeBWorK administrators to new course</code> and <code>Copy simple configuration file to new course</code> checked
+
# Leave <code>Add WeBWorK administrators to new course</code> checked
 
# Add an additional instructor if you wish
 
# Add an additional instructor if you wish
 
# Copy templates from: <code>modelCourse</code> (the default action)
 
# Copy templates from: <code>modelCourse</code> (the default action)
  +
# Leave <code>Also copy simple configuration file</code> checked
 
# Click on <code>Add Course</code>
 
# Click on <code>Add Course</code>
 
# Click <code>Log into myTestCourse</code>
 
# Click <code>Log into myTestCourse</code>
Line 850: Line 901:
 
At some point you will probably want to "hide" <code>myTestCourse</code> from general view but you already know how to do that.
 
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 ==
+
== 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>.
+
We will test out a few important parts of WeBWorK. If you run into problems, you should look at the WeBWorK app error log which is located at <code>/opt/webwork/webwork2/logs/webwork2.log</code> and/or the Apache error log which is located at <code>/var/log/apache2/error.log</code> and/or the nginx error log located at <code>/var/log/nginx/error.log</code>.
   
Click on <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select <code>Import</code>, select <code>setDemo.def</code> from the <code>Import from where</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>
+
Click on <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select <code>Import</code>, select <code>setDemo.def</code> from the <code>Import from where</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>Import</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 displayed nicely by MathJax (right click on the equation for info). You can also display equations as images but this is not recommended. If you do and have problems, 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.
+
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 displayed nicely by MathJax (right click on the equation for info). You can also display equations as images but this is not recommended.
   
Note that since you probably used "admin" to login you have Permission Level "admin" so things look more complicated than if you were just a regular professor with Permission Level "professor". In particular any time you view a problem, you have the option to "Edit tags" which you probably do not want to do. If these bothers you, login as a professor (see below).
+
Note that since you probably used "admin" to login you have Permission Level "admin" so things look a bit more complicated than if you were just a regular professor with Permission Level "professor". In particular any time you view a problem, you have the option to "Edit tags" which you probably do not want to do. If this bothers you, login as a professor (see below).
   
 
Continue looking at problems to see if everything is working properly.
 
Continue looking at problems to see if everything is working properly.
   
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. The page is a little complicated because you are an admin so you see the professor view (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>. If you get an error (you shouldn't) 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). If you want to preserve these tmp files, set <code>$WeBWorK::ContentGenerator::Hardcopy::PreserveTempFiles</code>
+
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. The page is complicated because you are an admin so you see the professor view (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>. If you get an error, then look at the various log files that are linked to on the output page (normally these files are removed if there are no errors). If you want to preserve these temporary files, then set <code>perserve_temp_files</code> to 1 in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.conf</code> and restart the webwork2 service. Remember to change <code>preserve_temp_files</code> back to 0 and restart the webwork2 service again or you will be saving a lot of unnecessary files. You can find these temporary files in <code>/opt/webwork/webwork2/tmp/</code>, then look under your course, <code>hardcopy</code>, and user. You will have to switch to being the root user to access the final subdirectory containing the tmp files.
to 1 in the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code> and then restart Apache. Remember to set this back to 0 after debugging. You can find these tmp files under <code>/opt/webwork/webwork2/tmp/</code>, then look under your course, <code>hardcopy</code>, and user. You will have to switch to being the root user to access the final subdirectory containing the tmp files.
 
   
 
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.
 
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>Open Problem Library </code> (actually it should already be selected so it will be greyed out)
+
As a final test click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library</code> (actually it should already be selected so it will be greyed out) 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. Note that if you just happen to view some statistics problems that require the R server, you will get errors (since we have not installed R --- at least not yet).
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. Note that if you just happen to view some statistics problems that require the R server, you will get errors (since we have not installed R --- at least not yet).
 
   
'''Note:''' if when using the <code>Library Browser</code> you find that after selecting a <code>Subject</code>, you can not select a <code>Chapter</code> (and usually you will see an error from setmaker.js: /webwork2/instructorXMLHandler: e.g. Timeout or Forbidden),
+
'''Note:''' if when using the <code>Library Browser</code> you find that after selecting a <code>Subject</code>, you can not select a <code>Chapter</code> (and usually an error toast will be shown), the most common reason is that $server_root_url has not been set "correctly" in the <code>/opt/webwork/webwork2/conf/site.conf</code> file. A common error is to use forget http:// or to use http:// when you should use https:// or to just have the wrong domain name or ip address. But sometimes "localhost" will work when the correct ip address or url will not, for example in situations when you are using a virtual machine as your host.
the most common reason is that $server_root_url has not been set "correctly" in the <code>/opt/webwork/webwork2/conf/site.conf</code> file. A common error is to use forget http:// or to use http:// when you should use https:// or to just have the wrong domain name or ip address. But sometimes "localhost" will work when the correct ip address or url will not, for example in situations when you are using a virtual machine as your host.
 
   
 
If all the above tests work, you can be pretty confident that WeBWorK is working properly.
 
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 <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. Also you can Import <code>set0.def</code> and <code>setMAAtutorial.def</code> and look through those problems.
+
Go back to <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select <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. Also you can Import <code>set0.def</code> and <code>setMAAtutorial.def</code> and look through those problems. Note that most of these sets date from the early days of WeBWorK in the 1990's and the problems they contain, while they still work, are not examples of current good programing practices. For current programing methods, look at e.g. https://webwork.maa.org/wiki/Category:PGM. Further, Problem 12 in setMAAtutorial (file htmllinksexample.pg) contains a simple error which is typical of errors you might make in authoring your own problems. WeBWorK tries to tell you what the error is and you can use the <code>Edit</code> button to edit and save the problem. Problem 2 in set0 (file prob1a.pg) may contain more subtle errors. The Open Problem Library (OPL) contains over 37,000 problems the vast majority of which are error free.
   
If you are new to WeBWorK or even if you are a pro, 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 or admin interfaces. Also for the same reason you should probably add professor to myTestCourse and log in as that professor to see what the professor interface looks like.
+
If you are new to WeBWorK or even if you are a pro, 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 or admin interfaces. Also for the same reason you should probably add a professor to myTestCourse and log in as that professor to see what the professor interface looks like.
   
 
Click on <code>Classlist Editor</code> on the <code>Main Menu</code>.
 
Click on <code>Classlist Editor</code> on the <code>Main Menu</code>.
Line 892: Line 943:
 
You can also add "practice users" and login as one of those to see how you can grant partial access to your course for practice or other reasons (e.g. auditors who don't want to be graded). To do this Click on <code>Classlist Editor</code>, select <code>Import</code>, select the "demoCourse.lst" (the only classlist available at this point) and hit <code>Take Action!</code>.
 
You can also add "practice users" and login as one of those to see how you can grant partial access to your course for practice or other reasons (e.g. auditors who don't want to be graded). To do this Click on <code>Classlist Editor</code>, select <code>Import</code>, select the "demoCourse.lst" (the only classlist available at this point) and hit <code>Take Action!</code>.
   
==More House Keeping==
+
== More House Keeping ==
   
===Hide the admin and myTestCourse courses===
+
=== Hide the admin and myTestCourse courses ===
 
Log out of myTestCourse if you are logged in and go to the WeBWorK Welcome page. Click on Course Administration and login as admin with the new admin password you set for the admin course.
 
Log out of myTestCourse if you are logged in and go to the WeBWorK Welcome page. Click on Course Administration and login as admin with the new admin password you set for the admin course.
 
Select "Hide Inactive Courses" and select the courses you want to hide and hit "Hide Courses". If you go back to the WeBWorK Welcome page, you will see no courses listed. You can still
 
Select "Hide Inactive Courses" and select the courses you want to hide and hit "Hide Courses". If you go back to the WeBWorK Welcome page, you will see no courses listed. You can still
 
access these courses directly by
 
access these courses directly by
<nowiki>http://192.168.76.128/webwork2/admin</nowiki>
+
<nowiki>http://yoursite.edu/webwork2/admin</nowiki>
<nowiki>http://192.168.76.128/webwork2/mytestcourse</nowiki>
+
<nowiki>http://yoursite.edu/webwork2/myTestCourse</nowiki>
where of course you should use your actual ip address or url.
+
where of course you should use your actual url.
   
===Replace the default landing page===
+
=== Replace the default landing page ===
You probably should replace <code>/var/www/html/index.html</code> with a page which redirects to the webwork course list at your site. Something like the following should work:
+
If serving webwork2 via a proxy by another web server, then you probably should replace <code>/var/www/html/index.html</code> with a page which redirects to the webwork course list at your site. If serving webwork2 directly, then the same can be accomplished by editing <code>/opt/webwork/webwork2/htdocs/index.html</code> (unless you are using the <code>server_root_url_redirect:</code> setting instead). Something like the following should work:
   
<html>
+
<html>
<head>
+
<head>
<META http-equiv="Pragma" content="no-cache">
+
<meta http-equiv="Pragma" content="no-cache">
<META HTTP-EQUIV="Refresh" CONTENT="0;URL=https://mysite.mydomain.edu/webwork2/">
+
<meta http-equiv="Refresh" content="0;url=<nowiki>https://mysite.mydomain.edu/webwork2/</nowiki>">
<title>WeBWorK site - redirects to main page</title>
+
<title>WeBWorK site - redirects to main page</title>
</head>
+
</head>
<body style="text-align: center;">
+
<body style="text-align: center;">
You probably want to use the
+
You probably want to use the
<a href="https://mysite.mydomain.edu/webwork2/">the WeBWorK list of courses page</a>
+
<a href="<nowiki>https://mysite.mydomain.edu/webwork2/</nowiki>">the WeBWorK list of courses page</a>
</body>
+
</body>
</html>
+
</html>
   
===Institution Logo===
+
=== Institution Logo ===
 
The institution logo (which is the MAA logo by default) appears on every WeBWorK page. You can replace with you own logo by doing the following. We took these directions verbatim from Alex Jordan's Forum post https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5642.
 
The institution logo (which is the MAA logo by default) appears on every WeBWorK page. You can replace with you own logo by doing the following. We took these directions verbatim from Alex Jordan's Forum post https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5642.
   
Line 937: Line 988:
 
<code>/opt/webwork/courses/Course_Name/course.conf</code>.
 
<code>/opt/webwork/courses/Course_Name/course.conf</code>.
   
==Optional Configurations==
+
== Optional Configurations ==
 
You should definitely consider implementing the following optional configurations.
 
You should definitely consider implementing the following optional configurations.
   
'''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (SSL) with an https: URL.
+
'''Option A''' configures the server so that access to WeBWorK will be through an encrypted connection (SSL) with an https: URL.
   
 
'''Option B''' installs and configures the R server for statistical computing. Many statistics and probability problems (mostly contributed by faculty at the University of British Columbia) require this.
 
'''Option B''' installs and configures the R server for statistical computing. Many statistics and probability problems (mostly contributed by faculty at the University of British Columbia) require this.
   
 
'''Option C''' sets up log rotation for WeBWorK's timing log.
 
'''Option C''' sets up log rotation for WeBWorK's timing log.
===Implement Option A (SSL)===
+
=== Implement Option A (SSL) ===
'''Option A''' configures apache so that access to WeBWorK will be through an encrypted connection (SSL) with an https: URL. Note that TLS is the successor protocol to SSL and is used everywhere. So that when we and others use the more common acronym SSL, we really are talking about TLS.
+
'''Option A''' configures the server so that access to WeBWorK will be through an encrypted connection (SSL) with an https: URL. Note that TLS is the successor protocol to SSL and is used everywhere. So that when we and others use the more common acronym SSL, we really are talking about TLS.
  +
  +
Note that there are very explicit instructions for setting up an SLL connection using the WeBWorK AMI image, Certbot, and Hypnotoad at [[WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image#Set_up_WeBWorK_to_use_SSL]] which may be useful.
   
 
First we have to obtain an official SSL certificate or generate a self-signed one which can be used for testing purposes. If students will be using your server, it is better to obtain an official SSL certificate since using a self-signed certificate with cause warning messages to be displayed when students connect to the server.
 
First we have to obtain an official SSL certificate or generate a self-signed one which can be used for testing purposes. If students will be using your server, it is better to obtain an official SSL certificate since using a self-signed certificate with cause warning messages to be displayed when students connect to the server.
   
====Obtain an Official SSL Certificate====
+
==== Obtain an Official SSL Certificate ====
 
Talk to the networking group on your campus about obtaining an official certificate. You can find information on the net about certificate providers, e.g. http://www.sslshopper.com/certificate-authority-reviews.html . Certbot (https://certbot.eff.org/) which uses Let's Encrypt certificates (https://letsencrypt.org/) is a good option if you are not using your organization's official certificates.
 
Talk to the networking group on your campus about obtaining an official certificate. You can find information on the net about certificate providers, e.g. http://www.sslshopper.com/certificate-authority-reviews.html . Certbot (https://certbot.eff.org/) which uses Let's Encrypt certificates (https://letsencrypt.org/) is a good option if you are not using your organization's official certificates.
   
 
The certificate goes in <code>/etc/ssl/certs/</code> and the key file goes in <code>/etc/ssl/private/</code>.
 
The certificate goes in <code>/etc/ssl/certs/</code> and the key file goes in <code>/etc/ssl/private/</code>.
   
====Use a self-signed Certificate====
+
==== Use a self-signed Certificate ====
   
When we installed the package openssh-server a self-signed certificate was automatically created. The certificate is stored at
+
First we need to install a package which is needed for openssh-server to generate a self-signed certificate.
/etc/ssl/certs/ssl-cert-snakeoil.pem
 
and the private key at
 
/etc/ssl/private/ssl-cert-snakeoil.key
 
   
This certificate and key may be regenerated manually with the following command (needs root privileges ie sudo):
 
  +
$ sudo apt-get install ssl-cert
   
  +
Then run
 
$ sudo make-ssl-cert generate-default-snakeoil --force-overwrite
 
$ sudo make-ssl-cert generate-default-snakeoil --force-overwrite
[sudo] password for wwadmin: <wwadmin password>
 
   
which you might want to do since I believe the original certificate is only valid for 365 days.
 
  +
This creates a certificate stored at
  +
/etc/ssl/certs/ssl-cert-snakeoil.pem
  +
and a private key at
  +
/etc/ssl/private/ssl-cert-snakeoil.key
  +
  +
I believe this certificate is only valid for 365 days. You can generate a new certificate with the same command.
   
 
In the instructions below we will use the provided self-signed certificate (ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key) but you can also generate your own using openssh following instructions on the web. As we said above, for a production server, you should really use an official certificate.
 
In the instructions below we will use the provided self-signed certificate (ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key) but you can also generate your own using openssh following instructions on the web. As we said above, for a production server, you should really use an official certificate.
   
====Set up Apache to use SSL====
+
==== Set up the Server to use SSL ====
  +
  +
Now we need to set up the server to use the SSL certificates. Choose your deployment option below and follow the directions for that option.
  +
  +
Our self-signed certificate and key files are named <code>/etc/ssl/certs/ssl-cert-snakeoil.pem</code> and <code>/etc/ssl/private/ssl-cert-snakeoil.key</code>. If you are using official files, use their file names instead. Additional configuration may also be needed in some cases. Instructions for doing so are beyond the scope of this document. You might look at https://docs.mojolicious.org/Mojo/Server/Daemon#listen for direct deployment via hypnotoad (you could also try using https://metacpan.org/pod/Mojo::ACME for letsencrypt), https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-ubuntu-22-04 for apache2, or https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-22-04 for nginx.
  +
  +
===== Set up Hypnotoad to use SSL (Option 1) =====
  +
  +
The only thing that needs to be done is to tell hypnotoad where the certificates are. For this edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> and in the <code>hypnotoad:</code> section change
  +
  +
listen:
  +
- <nowiki>http://*:8080</nowiki>
  +
to
  +
listen:
  +
- <nowiki>https://*:443?cert=/etc/ssl/certs/ssl-cert-snakeoil.pem&key=/etc/ssl/private/ssl-cert-snakeoil.key</nowiki>
  +
  +
Make sure that the files are readable by the webwork2 app.
  +
  +
$ sudo chown www-data /etc/ssl/certs/ssl-cert-snakeoil.pem /etc/ssl/private/ssl-cert-snakeoil.key
  +
  +
The webwork2 app needs to be restarted for this to take effect, but we will delay that until a bit later. Go to the check site.conf section below.
  +
  +
===== Set up Apache to use SSL (Option 2) =====
   
 
First we enable the <code>mod_ssl</code> module
 
First we enable the <code>mod_ssl</code> module
 
$ sudo a2enmod ssl
 
$ sudo a2enmod ssl
[sudo] password for wwadmin: <wwadmin password>
 
   
 
Now we have to configure Apache to use SSL.
 
Now we have to configure Apache to use SSL.
 
$ cd /etc/apache2/sites-available/
 
$ cd /etc/apache2/sites-available/
$ sudo cp default-ssl.conf default-ssl.conf.bak1
+
$ sudo cp default-ssl.conf default-ssl.conf.bak
[sudo] password for wwadmin: <wwadmin password>
 
 
$ sudo nano default-ssl.conf
 
$ sudo nano default-ssl.conf
 
Our self-signed certificate and key files are named
 
<code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code>. If you
 
are using official files, put their names in the lines below. You will also have to edit the Certificate Chain, Certificate Authority and possibly other items. Instructions for doing so are beyond the scope of this document. You might look at
 
https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-ubuntu-22-04
 
   
 
Search for the lines
 
Search for the lines
Line 992: Line 1,042:
 
Then save the file and quit. And enable <code>default-ssl.conf</code>
 
Then save the file and quit. And enable <code>default-ssl.conf</code>
 
$ sudo a2ensite default-ssl.conf
 
$ sudo a2ensite default-ssl.conf
[sudo] password for wwadmin: <wwadmin password>
 
 
Finally we restart Apache
 
Finally we restart Apache
 
$ sudo systemctl restart apache2
 
$ sudo systemctl restart apache2
Line 998: Line 1,047:
 
If you are using the snakeoil certificates you will see warning messages (e.g. NET::ERR_CERT_AUTHORITY_INVALID) and you will be asked to accept the risk. After you do so things should work just as before except that the connection will be via https.
 
If you are using the snakeoil certificates you will see warning messages (e.g. NET::ERR_CERT_AUTHORITY_INVALID) and you will be asked to accept the risk. After you do so things should work just as before except that the connection will be via https.
   
====Redirect http requests to https====
+
====== Redirect http requests to https ======
 
Assuming that everything is working, the next thing we do is set things up so that requests to <nowiki>http://yourserver.yourschool.edu/webwork2/</nowiki> are automatically redirected to <nowiki>https://yourserver.yourschool.edu/webwork2/</nowiki>.
 
Assuming that everything is working, the next thing we do is set things up so that requests to <nowiki>http://yourserver.yourschool.edu/webwork2/</nowiki> are automatically redirected to <nowiki>https://yourserver.yourschool.edu/webwork2/</nowiki>.
   
 
$ cd /etc/apache2/sites-available
 
$ cd /etc/apache2/sites-available
$ sudo cp 000-default.conf 000-default.conf.bak1
+
$ sudo cp 000-default.conf 000-default.conf.bak
[sudo] password for wwadmin: <wwadmin password>
 
 
$ sudo nano 000-default.conf
 
$ sudo nano 000-default.conf
   
Line 1,014: Line 1,063:
 
Then save the file and quit.
 
Then save the file and quit.
 
Restart Apache
 
Restart Apache
$ sudo service apache2 restart
+
$ sudo systemctl restart apache2
 
and try connecting to <nowiki>http://yourserver.yourschool.edu/webwork2/</nowiki>. The real connection should be through <nowiki>https://yourserver.yourschool.edu/webwork2/</nowiki>.
 
and try connecting to <nowiki>http://yourserver.yourschool.edu/webwork2/</nowiki>. The real connection should be through <nowiki>https://yourserver.yourschool.edu/webwork2/</nowiki>.
   
====Check site.conf====
 
  +
===== Set up Nginx to use SSL (Option 3) =====
  +
  +
You should identify the correct file to use for your system if you have already created an Nginx site configuration file. If you have not then a good starting point is to copy <code>/etc/nginx/sites-available/default</code> to <code>/etc/nginx/conf.d/default-ssl.conf</code> and modify that. Add the lines
  +
  +
ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
  +
ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
  +
  +
to the file after the <code>listen</code> lines near the beginning of the <code>server</code> section. The contents of the file should now look something like the following.
  +
  +
server {
  +
listen 443 ssl default_server;
  +
listen [::]:443 ssl default_server;
  +
  +
ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
  +
ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
  +
  +
root /var/www/html;
  +
  +
index index.html index.htm;
  +
  +
server_name yourserver.yourdomain.edu;
  +
  +
location / {
  +
# First attempt to serve request as file, then
  +
# as directory, then fall back to displaying a 404.
  +
try_files $uri $uri/ =404;
  +
}
  +
  +
include /opt/webwork/webwork2/conf/webwork2.nginx.conf;
  +
}
  +
  +
Restart Nginx for this to take effect.
  +
$ sudo systemctl restart nginx
  +
  +
You should now be able to open the url <nowiki>https://yourserver.yourdomain.edu/webwork2</nowiki> in a browser.
  +
  +
====== Redirect http requests to https ======
  +
  +
Add the following to the beginning of your nginx site configuration file.
  +
  +
server {
  +
listen 80 default_server;
  +
listen [::]:80 default_server;
  +
server_name yourserver.yourdomain.edu;
  +
return 301 <nowiki>https://yourserver.yourdomain.edu</nowiki>$request_uri;
  +
}
  +
  +
Restart Nginx for this to take effect.
  +
$ sudo systemctl restart nginx
  +
  +
You should now be able to open the url <nowiki>http://yourserver.yourdomain.edu/webwork2</nowiki> in a browser and it will automatically be redirected to <nowiki>https://yourserver.yourdomain.edu/webwork2</nowiki>.
  +
  +
==== Check site.conf ====
 
'''This is important'''. We have to check the value of $server_root_url in webwork2/conf/site.conf to make
 
'''This is important'''. We have to check the value of $server_root_url in webwork2/conf/site.conf to make
 
sure it uses https (so it should read e.g. <nowiki>https://yourserver.yourschool.edu</nowiki>). If
 
sure it uses https (so it should read e.g. <nowiki>https://yourserver.yourschool.edu</nowiki>). If
Line 1,029: Line 1,130:
 
In the line
 
In the line
 
$server_root_url = ...
 
$server_root_url = ...
replace http by https if necessary. Then save the file, quit and restart apache
+
replace http by https if necessary. Then save the file, quit and restart webwork2
sudo service apache2 restart
+
sudo systemctl restart webwork2
[sudo] password for wwadmin: <wwadmin password>
 
   
===Implement Option B (Rserve)===
+
=== Implement Option B (Rserve) ===
   
 
Here we will install and configure the R server for statistical computing. Many statistics and probability problems (mostly contributed by faculty at the University of British Columbia) require this.
 
Here we will install and configure the R server for statistical computing. Many statistics and probability problems (mostly contributed by faculty at the University of British Columbia) require this.
Line 1,038: Line 1,139:
 
See the documentation (from which we have borrowed heavily) [[R_in_WeBWorK]] for more detailed information.
 
See the documentation (from which we have borrowed heavily) [[R_in_WeBWorK]] for more detailed information.
   
====Install the R server====
+
==== Install the R server ====
 
$ sudo apt install r-cran-rserve
 
$ sudo apt install r-cran-rserve
[sudo] password for wwadmin: <wwadmin password>
 
   
 
and check that R is running
 
and check that R is running
Line 1,057: Line 1,157:
 
Save workspace image? [y/n/c]: n
 
Save workspace image? [y/n/c]: n
   
====Configure Webwork with the location of the R server====
+
==== Configure Webwork with the location of the R server ====
   
 
We have to edit the localOverrides.conf file.
 
We have to edit the localOverrides.conf file.
Line 1,064: Line 1,164:
   
 
Search for the line
 
Search for the line
#$pg{specialPGEnvironmentVars}{entryAssist} = 'WIRIS';
+
#$pg{specialPGEnvironmentVars}{entryAssist} = 'MathView';
 
and under that line add the following
 
and under that line add the following
 
 
Line 1,074: Line 1,174:
 
Then save the file and Quit.
 
Then save the file and Quit.
   
====Set up Rserve to run as a daemon at system boot====
+
==== Set up Rserve to run as a daemon at system boot ====
   
 
This is somewhat complicated. I'm basically following instructions from https://github.com/geordielad/rserve-systemd-unit
 
This is somewhat complicated. I'm basically following instructions from https://github.com/geordielad/rserve-systemd-unit
Line 1,081: Line 1,181:
   
 
$ sudo adduser rserveuser --system --shell=/bin/false --no-create-home --disabled-password --disabled-login
 
$ sudo adduser rserveuser --system --shell=/bin/false --no-create-home --disabled-password --disabled-login
 
   
 
Next we create a file to automatically start Rserve
 
Next we create a file to automatically start Rserve
Line 1,112: Line 1,211:
   
 
$ sudo chown root:root rserve.service
 
$ sudo chown root:root rserve.service
[sudo] password for wwadmin: <wwadmin password>
 
 
$ sudo mv rserve.service /etc/systemd/system
 
$ sudo mv rserve.service /etc/systemd/system
 
$ sudo systemctl daemon-reload
 
$ sudo systemctl daemon-reload
Line 1,125: Line 1,223:
 
$ sudo ln -s ../site-library/Rserve/libs/Rserve.dbg
 
$ sudo ln -s ../site-library/Rserve/libs/Rserve.dbg
   
====Test that things are working properly====
+
==== Test that things are working properly ====
   
 
First start Rserve manually
 
First start Rserve manually
 
$ sudo systemctl start rserve
 
$ sudo systemctl start rserve
[sudo] password for wwadmin: <wwadmin password>
 
 
and run
 
and run
 
$ sudo lsof -i -P -n | grep LISTEN
 
$ sudo lsof -i -P -n | grep LISTEN
Line 1,141: Line 1,238:
 
Finally reboot your server (to test that the Rserve starts automatically on boot up) and run
 
Finally reboot your server (to test that the Rserve starts automatically on boot up) and run
 
$ sudo systemctl status rserve.service
 
$ sudo systemctl status rserve.service
[sudo] password for wwadmin: <wwadmin password>
 
 
to check that all is well and just to be redundant
 
to check that all is well and just to be redundant
 
$ sudo lsof -i -P -n | grep LISTEN
 
$ sudo lsof -i -P -n | grep LISTEN
 
again. Now we are sure that Rserve automatically starts when the system is booted.
 
again. Now we are sure that Rserve automatically starts when the system is booted.
   
====Loading additional modules====
+
==== Loading additional modules ====
 
This step should not be necessary unless you are writing or using WeBWorK problems that need additional resources beyond what is loaded by default. An example is using R to compute complex eigenvalues which requires the <code>Math::Complex</code> module (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5577). The error message in such a case would be similar to
 
This step should not be necessary unless you are writing or using WeBWorK problems that need additional resources beyond what is loaded by default. An example is using R to compute complex eigenvalues which requires the <code>Math::Complex</code> module (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5577). The error message in such a case would be similar to
 
Can't locate object method "make" via package "Math::Complex" (perhaps you forgot to load "Math::Complex"?) at /usr/share/perl/5.30/Math/Complex.pm line 329
 
Can't locate object method "make" via package "Math::Complex" (perhaps you forgot to load "Math::Complex"?) at /usr/share/perl/5.30/Math/Complex.pm line 329
Line 1,168: Line 1,264:
 
and under the line
 
and under the line
 
#push (@{${pg}{modules}}, [qw(TikZ_Image2)]);
 
#push (@{${pg}{modules}}, [qw(TikZ_Image2)]);
add the lines
+
add the line
push @{$pg{modules}},
+
push @{$pg{modules}}, [qw(Math::Complex)];
[qw( Math::Complex )],
 
;
 
 
You can add as many modules as you need this way.
 
You can add as many modules as you need this way.
   
 
Then save the file and Quit.
 
Then save the file and Quit.
   
===Implement Option C (Logrotate)===
+
=== Implement Option C (Logrotate) ===
Here we will set up log rotation for WeBWorK's timing log which can grow huge especially if you have a large number of users. The <code>timing.log</code> gives timing information on every action in WeBWorK (see [[WeBWorK_performance]]) and can be used to assess the performance of your server.
+
Here we will set up log rotation for WeBWorK's timing log and webwork2 app log which can grow huge especially if you have a large number of users. The <code>timing.log</code> gives timing information on every action in WeBWorK (see [[WeBWorK_performance]]) and can be used to assess the performance of your server. The <code>webwork2.log</code> file contains webwork2 app log output including errors that can be useful for debugging issues.
   
====Create a WeBWorK configuration file for Logrotate====
+
==== Create a WeBWorK configuration file for Logrotate ====
 
Logrotate’s configuration files are located in <code>/etc/logrotate.d</code>. Now we create one for WeBWorK.
 
Logrotate’s configuration files are located in <code>/etc/logrotate.d</code>. Now we create one for WeBWorK.
   
Line 1,192: Line 1,288:
 
notifempty
 
notifempty
 
}
 
}
and then save the file and quit. The backup will be done weekly and we are keeping 15 weeks (approximately one semester) worth of logs.
 
  +
  +
/opt/webwork/webwork2/logs/webwork2.log {
  +
su www-data www-data
  +
weekly
  +
missingok
  +
rotate 15
  +
compress
  +
delaycompress
  +
notifempty
  +
copytruncate
  +
}
  +
and then save the file and quit.
  +
  +
There is one additional step that is needed if you are [[Installation_Manual_for_2.18_on_Ubuntu#Option 1: Serving Directly via Hypnotoad|serving directly via hypnotoad]]. In that case the webwork2 application initially starts as the root user, and then switches to the www-data user, and the <code>webwork2.log</code> file is created by the root user before the switch is made. So the file's owner and group need to be fixed. You can do this by executing
  +
$ sudo chown www-data:www-data /opt/webwork/webwork2/logs/webwork2.log
  +
  +
The backup will be done weekly and we are keeping 15 weeks (approximately one semester) worth of logs.
 
The most recent backup will not be compressed but all older ones will be. We are not explicitly creating a new <code>timing.log</code> file
 
The most recent backup will not be compressed but all older ones will be. We are not explicitly creating a new <code>timing.log</code> file
 
because WeBWorK will automatically create one if it's missing. If you want to check that it works you can run <code>logrotate</code>
 
because WeBWorK will automatically create one if it's missing. If you want to check that it works you can run <code>logrotate</code>
Line 1,198: Line 1,310:
   
 
sudo logrotate -f /etc/logrotate.d/webwork
 
sudo logrotate -f /etc/logrotate.d/webwork
[sudo] password for wwadmin: <wwadmin password>
 
   
Then if you look in <code>/opt/webwork/webwork2/logs</code>, you should see
+
Then if you look in <code>/opt/webwork/webwork2/logs</code>, you should see the following files
   
  +
webwork2.log
  +
webwork2.log.1
 
timing.log.1
 
timing.log.1
   
 
You will not see a <code>timing.log</code> file unless someone has been doing something with WeBWorK. If there is no <code>timing.log</code> file
 
You will not see a <code>timing.log</code> file unless someone has been doing something with WeBWorK. If there is no <code>timing.log</code> file
do something yourself (e.g. login to a course) and then you should see
+
do something yourself (e.g. login to a course) and then you should see
   
  +
webwork2.log
  +
webwork2.log.1
 
timing.log
 
timing.log
 
timing.log.1
 
timing.log.1
Line 1,212: Line 1,327:
 
Now run <code>logrotate</code> again
 
Now run <code>logrotate</code> again
 
sudo logrotate -f /etc/logrotate.d/webwork
 
sudo logrotate -f /etc/logrotate.d/webwork
[sudo] password for wwadmin: <wwadmin password>
 
 
and do something in WeBWorK and you should see
 
and do something in WeBWorK and you should see
   
  +
webwork2.log
  +
webwork2.log.1
  +
webwork2.log.2.gz
 
timing.log
 
timing.log
 
timing.log.1
 
timing.log.1
 
timing.log.2.gz
 
timing.log.2.gz
   
Here is what is going on. <code>timing.log.1</code> was renamed to <code>timing.log.2</code> and compressed giving <code>timing.log.2.gz</code>. <code>timing.log</code> was renamed to <code>timing.log.1</code>.
 
  +
Here is what is going on. <code>timing.log.1</code> was renamed to <code>timing.log.2</code> and compressed giving <code>timing.log.2.gz</code>. <code>timing.log</code> was renamed to <code>timing.log.1</code>. A slightly different procedure occured for the <code>webwork2.log</code> file due to the <code>copytruncate</code> option. <code>webwork2.log.1</code> was renamed to <code>webwork2.log.2</code> and compressed giving <code>webwork2.log.2.gz</code>. That part is the same. However, <code>webwork2.log</code> was copied to <code>webwork2.log.1</code>, and <code>webwork2.log</code> was truncated. That means that the original <code>webwork2.log</code> file is still in place, but is now empty. This is important or the Mojolicious webwork2 app would lose its handle on the file and stop writing to it. A similar procedure will happen weekly until there are a total of 15 backups of each file after which the oldest one will be deleted.
And the something you (or someone else) did in WeBWorK created a new <code>timing.log</code> file. A similar procedure will happen weekly until there are a total of
 
15 backups after which the oldest one will be deleted.
 
   
==Known Issues==
+
== Known Issues ==
 
Here are the known issues with this release.
 
Here are the known issues with this release.
===PGbasicmacros.pl===
+
=== PGbasicmacros.pl ===
 
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) in the text (not in Math Mode) of a WeBWorK problem fails. An example is Problem 1 in Set 0 in "myTestCourse" (see [[#Test that Things are Working Properly|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.
 
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) in the text (not in Math Mode) of a WeBWorK problem fails. An example is Problem 1 in Set 0 in "myTestCourse" (see [[#Test that Things are Working Properly|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.
   
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file.
+
If you do want to proceed with the fix we need to edit the PGbasicmacros.pl file.
 
$ cd /opt/webwork/pg/macros
 
$ cd /opt/webwork/pg/macros
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1
+
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak
   
 
$ nano PGbasicmacros.pl
 
$ nano PGbasicmacros.pl
Line 1,241: Line 1,356:
 
Then save the file and Quit.
 
Then save the file and Quit.
   
==Housekeeping==
+
== Housekeeping ==
===Remove temporary files===
+
=== Remove temporary files ===
 
WebWorK no longer generates a lot of temporary files but it is still a good idea to clean them out once in awhile. Temporary files are stored under the directories <code>/opt/webwork/webwork2/tmp</code> and <code>/opt/webwork/webwork2/htdocs/tmp</code>. It is safe to delete everything in these tmp directories. If you want, you can follow the directions below to set up Cron jobs to do this automatically.
 
WebWorK no longer generates a lot of temporary files but it is still a good idea to clean them out once in awhile. Temporary files are stored under the directories <code>/opt/webwork/webwork2/tmp</code> and <code>/opt/webwork/webwork2/htdocs/tmp</code>. It is safe to delete everything in these tmp directories. If you want, you can follow the directions below to set up Cron jobs to do this automatically.
 
 
====Using Cron Jobs to remove temporary files====
+
==== Using Cron Jobs to remove temporary files ====
   
 
It is a good idea to clean out temporary files on a regular automatic schedule. The following two cron jobs will accomplish this. They are run every six months (in January and July), on the first and second days of the month at 0330 hours. These cron jobs should be run as root. We use <code>crontab</code> to edit the <code>crontab</code> file:
 
It is a good idea to clean out temporary files on a regular automatic schedule. The following two cron jobs will accomplish this. They are run every six months (in January and July), on the first and second days of the month at 0330 hours. These cron jobs should be run as root. We use <code>crontab</code> to edit the <code>crontab</code> file:
$ sudo -s
+
$ sudo crontab -e
[sudo] password for wwadmin: <wwadmin password>
 
# crontab -e
 
   
 
Now add the following lines at the end of the file
 
Now add the following lines at the end of the file
Line 1,255: Line 1,370:
 
30 03 2 1,7 * find /opt/webwork/webwork2/htdocs/tmp/* -name "*" ! -name "README" -delete
 
30 03 2 1,7 * find /opt/webwork/webwork2/htdocs/tmp/* -name "*" ! -name "README" -delete
   
and save the file and quit. Then exit acting as root
+
and save the file and quit.
# exit
 
$
 
   
==Where to go From Here ==
+
== 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>.
 
You should play around with <code>myTestCourse</code> e.g. click on <code>Library Browser</code> and browse the <code>Problem Library</code>.
Line 1,266: Line 1,381:
   
 
Under Categories below click on Administrators to see a listing of other WeBWorK documentation for system administrators.
 
Under Categories below click on Administrators to see a listing of other WeBWorK documentation for system administrators.
 
-- Main.ArnoldPizer and Peter Staab - August 4, 2022 <br />
 
   
 
[[Category:Administrators]]
 
[[Category:Administrators]]

Latest revision as of 00:22, 9 January 2024


These instructions cover the installation of WeBWorK 2.18 for Ubuntu Server 22.04 LTS.

Other installation methods (which are faster and easier) include using the WeBWorK Virtual Machine Image (see Installing WeBWorK from a Virtual Machine Image) which has been tested on VMware, VirtualBox and QEMU/KVM and using the WeBWorK AMI if you want to run your server on AWS (see WeBWorK Amazon Machine Images (AMI's)).


If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see Release notes for WeBWorK 2.18#Upgrade Instructions.

Contents

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

Note that we will use wwadmin to refer to your administrative user on the system. In practice you should NOT actually use wwadmin for your administrative user name. Using a fixed user name that is publicly known is a security vulnerability.

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

Code blocks for command to enter in the shell begin with $. You are not intended to type the $ character as part of the provided commands.

Note that many commands begin with sudo. These commands are executed with super user privileges. You will need to enter your password for the first invocation of one of these commands which will begin a super user session. That session will timeout typically 15 minutes after the last entered sudo command, and you will need to enter your password again. You can also enter a super user shell with sudo -s. However, it is not advisable to do so. This is an unsafe practice. Forgetting to exit the super user shell is a common mistake that can lead to disastrous consequences if the wrong command is executed with the elevated privileges.

Install the Ubuntu 22.04 Server Operating System

Installation

Connect to http://www.ubuntu.com/ for information. We recommend you use the "Long Term Support" (LTS) version of Ubuntu which is currently version 22.04. The next LTS release will be version 24.04 to be released in April, 2024.

The installation process consists of a series of steps or panels. In the panels, generally you will use <Tab> or the up and down arrows to navigate, the <Space> bar to check a box and the <Enter> key to confirm an action. On the "Chose type of install" panel, select the default "Ubuntu Server", not the "Ubuntu Server (minimized)"

Enter the information for the steps until you get to the "Profile setup".

Profile Setup

What you fill in for the "Profile setup" is a privileged user so you might want to enter a special administrative account rather than your normal account. You can use whatever you want. Do NOT use wwadmin, but this is what will be referred to in these instructions by wwadmin.

  • Enter the information for "Your name"
  • Enter the information for "Your Computer's name"
  • Enter the information for "Pick a username" In these instructions, we will call this name wwadmin.
  • Enter the information twice for the password. In these instructions, you will need to enter this password for sudo commands. DO NOT FORGET WHAT YOU ENTER HERE.
  • Then select Done and press <Enter>.


SSH Setup
Select "Install OpenSSH server". Then select Done and press <Enter>.
Featured Server Snaps
Do not select any server snaps. Then select Done and press <Enter>.

Now sit back and relax while the installation takes place. This should be pretty quick. When you finally see "Reboot Now", press <Enter> and log into your server.

Accessing Your Server Remotely

At this point you can login your server from a remote location using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are).

You can do all of the remaining installation from a remote location if you wish. The advantage of doing this is that you can copy commands from these instructions (with copy from the Edit menu or ^C) and paste them into a terminal window (with paste from the Edit menu list or <Shift> <Ctrl> <V> or <Shift> <Insert> depending on your application). This is an excellent way to use these instructions since it is fast and insures commands are entered correctly (just be careful to read before you run the command and replace things like database_password with the correct code in the few places such things occur).

Assuming your network has been set up, type

$ ip addr show 

and you will see something like

...
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33
...

Here 192.168.76.128 is the ip address of your server. Note that you should ignore the loopback address 127.0.0.1.

Fully Qualified Domain Name

Now we have to set your server's fully qualified domain name. Note that if your network was set up automatically via DHCP, your server's fully qualified domain name should already be set up. You can check by running the hostname commands below.

Run the command

sudo hostnamectl set-hostname webwork

where of course you should replace webwork by whatever your server's name is.

You can check these settings by running the commands

$ hostname --fqdn

and

$ hostname

The first gives the server's fully qualified domain name (e.g. webwork.mydepartment.myschool.edu) and the second the server's name (e.g. webwork).

Install Software Packages

Ubuntu Software Packages

The following instructions will install necessary software packages. You may first have to run the commands

$ sudo apt update
$ sudo apt upgrade

to update package locations and upgrade. Restart all services if requested.

Here is the list of Ubuntu packages that need to be installed.

  1. cm-super
  2. cpanminus
  3. curl
  4. dvipng
  5. dvisvgm
  6. gcc
  7. git
  8. imagemagick
  9. libarchive-zip-perl
  10. libarray-utils-perl
  11. libclass-tiny-antlers-perl
  12. libcrypt-jwt-perl
  13. libcryptx-perl
  14. libdata-dump-perl
  15. libdata-structure-util-perl
  16. libdatetime-perl
  17. libemail-stuffer-perl
  18. libexception-class-perl
  19. libfile-find-rule-perl
  20. libfile-sharedir-install-perl
  21. libfuture-asyncawait-perl
  22. libgd-perl
  23. libhttp-async-perl
  24. libiterator-perl
  25. libiterator-util-perl
  26. libjson-maybexs-perl
  27. libjson-perl
  28. liblocale-maketext-lexicon-perl
  29. libmath-random-secure-perl
  30. libminion-perl
  31. libminion-backend-sqlite-perl
  32. libmojolicious-perl
  33. libmojolicious-plugin-renderfile-perl
  34. libnet-ip-perl
  35. libnet-ldap-perl
  36. libnet-oauth-perl
  37. libossp-uuid-perl
  38. libpadwalker-perl
  39. libpandoc-wrapper-perl
  40. libpath-class-perl
  41. libphp-serialization-perl
  42. libpod-wsdl-perl
  43. libsoap-lite-perl
  44. libsql-abstract-classic-perl
  45. libstring-shellquote-perl
  46. libsvg-perl
  47. libtemplate-perl
  48. libtext-csv-perl
  49. libtimedate-perl
  50. libuniversal-can-perl
  51. libuniversal-isa-perl
  52. libuuid-tiny-perl
  53. libxml-parser-easytree-perl
  54. libxml-parser-perl
  55. libxml-writer-perl
  56. libyaml-libyaml-perl
  57. make
  58. netpbm
  59. openssh-server
  60. pdf2svg
  61. preview-latex-style
  62. texlive
  63. texlive-latex-extra
  64. texlive-science
  65. unzip

To install all of these packages in one fell swoop run the command (obviously you want to use cut and paste)

$ sudo apt install cm-super cpanminus curl dvipng dvisvgm gcc git imagemagick \
libarchive-zip-perl libarray-utils-perl libclass-tiny-antlers-perl \
libcrypt-jwt-perl libcryptx-perl libdata-dump-perl libdata-structure-util-perl \
libdatetime-perl libemail-stuffer-perl libexception-class-perl \
libfile-find-rule-perl libfile-sharedir-install-perl libfuture-asyncawait-perl \
libgd-perl libhttp-async-perl libiterator-perl libiterator-util-perl \
libjson-maybexs-perl libjson-perl liblocale-maketext-lexicon-perl \
libmath-random-secure-perl libminion-perl libminion-backend-sqlite-perl \
libmojolicious-perl libmojolicious-plugin-renderfile-perl libnet-ip-perl \
libnet-ldap-perl libnet-oauth-perl libossp-uuid-perl libpadwalker-perl \
libpandoc-wrapper-perl libpath-class-perl libphp-serialization-perl \
libpod-wsdl-perl libsoap-lite-perl libsql-abstract-classic-perl \
libstring-shellquote-perl libsvg-perl libtemplate-perl libtext-csv-perl \
libtimedate-perl libuniversal-can-perl libuniversal-isa-perl libuuid-tiny-perl \
libxml-parser-easytree-perl libxml-parser-perl libxml-writer-perl \
libyaml-libyaml-perl make netpbm openssh-server pdf2svg preview-latex-style \
texlive texlive-latex-extra texlive-science unzip

Accept any prompts with the default answer by hitting <Enter>. Restart all services if requested.

Installation of Other Perl Modules with cpanm

We will use cpanm to install other Perl modules that are not available as Ubuntu packages or a different version than the Ubuntu packaged version is needed. To install these modules execute

$ sudo cpanm --notest Statistics::R::IO Perl::Tidy@20220613 XML::LibXML

Note that --notest is added to avoid the unit tests that make the installation take considerably longer, and require the installation of additional dependencies used only for the tests.

Later we will check that all Perl modules have been properly installed.

Install a Database

This section installs MariaDB as the database manger for webwork. MariaDB is the recommended database but you can install and use MySQL if you wish.

Install and Testing MariaDB

Install MariaDB using the distribution and cpan packages.

$ sudo apt install mariadb-server libmariadb3 libmariadb-dev libdevel-checklib-perl
$ sudo cpanm DBD::MariaDB

Restart all services if requested.

Secure the Database

Then we should secure the database. Note that if you install MariaDB as suggested, all mysql commands automatically use MariaDB.

$ sudo mysql_secure_installation

To get started just hit <Enter> since there is no password set for root. You should answer n to the first two questions as is suggested and answer Y to all the remaining questions.

Now test that all is well:

$ sudo mysql

You should see

Welcome to the MariaDB monitor ...
MariaDB>

Now lets check the MariaDB users. To see the users, do the following

 MariaDB> SELECT user,authentication_string,plugin,host FROM mysql.user;

You will see a table with only three users: mariadb.sys, root and mysql.

Now exit MariaDB

MariaDB> exit
Bye
$

Starting and Stopping MariaDB (or MySQL)

On rare occasions you may need to start, stop, or restart the database server.

To start the MariaDB or MySQL server run the command

$ sudo systemctl start mysql

To stop the MariaDB or MySQL server run the command

$ sudo systemctl stop mysql

To restart the MariaDB or MySQL server run the command

$ sudo systemctl restart mysql

To obtain more information about the MariaDB or MySQL server run

$ systemctl status mysql

Connection Limits

Those coming from earlier versions of WeBWorK, especially 2.13 and 2.14, may have never run into connection limits on the SQL database write, depending on the total class enrollments. In 2.18, especially using hypnotoad (see below), the connection limit default of 151 connections can be reached fairly easily. So long as your system resources allow it, increasing this limit to approximately twice the number of workers used in the web serving can help prevent very scary errors from confusing your users. Edit the MariaDB conf file at:

$ sudo nano /etc/my.cnf

Beneath the first line, which should state something like:

[mysqld]

add a line to increase this number. For example, if the number of workers for your hypnotoad setup (below) was set to 250, then 500 might be an appropriate choice for the maximum number of connections.

Max_connections = [preferred new max digits]

(Aside) If you are using MySQL instead of MariaDB, this file is located at /etc/mysql/mysql.conf.d/mysql.cnf. Same setting, same information, just a different configuration location.

Install WeBWorK

We are at the point where we can start downloading and installing WeBWorK.

Note the instructions below assume you are installing WeBWorK from scratch. If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see Release notes for WeBWorK 2.18#Upgrade Instructions.

Create the Required Directories

$ sudo mkdir /opt/webwork
$ sudo chown wwadmin:wwadmin /opt/webwork
$ cd /opt/webwork
$ mkdir libraries courses

Reminder: You should use the account you selected to administer webwork instead of wwadmin above.

Download the WeBWorK System Software and Problem Libraries

We will use Git to download WeBWorK from Github. This is easy and it will also make it easy to update the system in the future. Note that for long commands it is much easier to copy (^C) them from this document and paste (<Shift><Ctrl><V> or <Shift><Insert>) them in a terminal window.

$ cd /opt/webwork
$ git clone https://github.com/openwebwork/webwork2.git
$ git clone https://github.com/openwebwork/pg.git
$ cd libraries
$ git clone https://github.com/openwebwork/webwork-open-problem-library.git

Important Note. The above commands retrieve the main branch which gives the latest stable release of the software package (webwork2, pg, etc.) with bug fixes. If a stable release newer than 2.18 exists, that will be downloaded and these instructions may be a little out of date. So it is a good idea to check before downloading. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/main/VERSION and https://github.com/openwebwork/pg/blob/main/VERSION.

The first and second download gives you the latest released versions of WeBWorK 2 and PG. The third download contains the WeBWorK Open Problem Library (OPL) which contains thousands of WeBWorK problems (over 37,000 currently).

The main information page about WebWorK downloads is available at http://webwork.maa.org/wiki/Category:Release_Notes

The main information page about the OPL is available at http://webwork.maa.org/wiki/Open_Problem_Library

Setup the Directory for Courses

Now copy content into courses directory.

$ cd /opt/webwork/webwork2/courses.dist
$ cp *.lst /opt/webwork/courses/
$ rsync -a modelCourse /opt/webwork/courses/

Set File and Directory Permissions

The PG installation directory and files should be owned by the primary wwadmin user and not writable by other users, but readable by all:

$ sudo chmod -R u+rwX,go+rX /opt/webwork/pg

Most WeBWorK directories and files should also be owned by the primary wwadmin user and not writable by other users, and again readable by all:

$ sudo chmod -R u+rwX,go+rX /opt/webwork/webwork2

Certain data directories need to be writable by the web server. These are DATA, courses, 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. We will use the default group for web services www-data.

It is helpful for the user administering webwork to be in this group. As above we are calling this user wwadmin. To add wwadmin to the www-data group,

$ sudo adduser wwadmin www-data

where of course you should replace wwadmin by the actual user name. You can check that this succeeded by running

$ id wwadmin

and then you should see www-data listed under groups.

Now we make the WeBWorK directories that need to be writable by the web server have www-data 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.

$ cd /opt/webwork/webwork2/
$ sudo chgrp -R www-data DATA ../courses htdocs/tmp logs tmp
$ sudo chmod -R g+w DATA ../courses htdocs/tmp logs tmp

Configure the Shell

To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.

Add the WeBWorK bin directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Go to your home directory and backup your .bashrc file

$ cd
$ cp .bashrc .bashrc.bak

Now edit .bashrc

$ nano .bashrc

After the last line add the three lines:

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

Then save the file and Quit.

Close your Terminal Window and open a new one so the above changes take effect. You can check that they have by

$ echo $PATH
$ echo $WEBWORK_ROOT
$ echo $PG_ROOT

Obtain Javascript Libraries

Install node and npm

WW 2.18 requires newer versions of node and npm than are in the Ubuntu repositories.

Note that if you have a previous version of node installed, then you will need to first uninstall it. To determine if this is the case run

$ node --version

If that shows vNN.??.? where NN is 16 or more, then you already have a new enough version of node installed. If that says Command 'node' not found, ..., then skip to installing node below. If a version is shown that does not start with 16 or more, then uninstall node with the commands:

$ sudo apt autoremove nodejs nodejs-doc
$ sudo rm /etc/apt/sources.list.d/nodesource.list
$ sudo apt update

Run the following commands to install node version 16 and npm version 8 from nodesource:

$ curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
$ sudo apt install -y nodejs

Installing Javascript Libraries

Javascript libraries are obtained using npm. This includes the following javascript packages:

  1. codemirror
  2. bootstrap
  3. flatpickr
  4. fontawesome
  5. iframe-resizer
  6. jquery
  7. jquery-ui
  8. mathjax
  9. sortablejs
  10. jsxgraph
  11. mathquill

Furthermore, all local javascript and css files are minimized, and the generated file names include a hash of the content. This ensures that browser's always are served up to date files when these files change, and prevent the need for users to need to refresh their browser cache.

To install all javascript dependencies and minimize local javascript and css:

$ cd /opt/webwork/webwork2/htdocs/
$ npm ci
$ cd /opt/webwork/pg/htdocs/
$ npm ci

Note that a message may be displayed stating that "Browserlist: caniuse-lite is outdated." You can safely ignore that message.

Miscellaneous System Patches

If the users of your system will be using problems that utilize the new PGtikz.pl macro then you will need to apply the following patch:

$ sudo patch -p1 -d / < /opt/webwork/webwork2/docker-config/imagemagick-allow-pdf-read.patch

Configure WeBWorK

Make Copies of the Distribution Configuration Files

Before configuring the system, you must make local copies of the site.conf and localOverrides.conf configuration files, located in /opt/webwork/webwork2/conf/ .

$ cd /opt/webwork/webwork2/conf
$ cp site.conf.dist site.conf
$ cp localOverrides.conf.dist localOverrides.conf

WeBWorK System Configuration

Most WeBWorK configuration is done in the files /opt/webwork/webwork2/conf/site.conf and /opt/webwork/webwork2/conf/localOverrides.conf. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files 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 localOverrides.conf) in the course.conf file. An instructor can only edit the course.conf file herself (for her own course) if she has "admin" privilege which by default instructors do not have. But most things instructors may want to customize and many others (language, timezone, permissions, display modes, email, ...) can be set using the Course Configuration page from within the course and such setting override those in the configuration files.

Actually there are three main configuration files, site.conf, defaults.config and localOverrides.conf. The reason there are three configuration files is to make upgrading WeBWorK easier.

  • site.conf: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, site.conf.dist will be.
  • defaults.config: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.
  • localOverrides.conf This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, localOverrides.conf.dist will be.

There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options.

Edit the site.conf file

Now edit site.conf

$ nano /opt/webwork/webwork2/conf/site.conf

First we have to add information about your site's URL. Search for server_root_url and edit the line so that it reads:

$server_root_url   = 'http://yourserver.yourschool.edu';

where of course you should edit yourserver.yourschool.edu appropriately. The "http://" is important. If you are running a secure server (i.e., using SSL - really TLS), the url should start with https: but you should wait to make that change until after WeBWorK is up and running and you set up SSL. In that case the "https://" is important.

If you would like to serve third party javascript and css files from a CDN instead of from your server, then change $options{thirdPartyAssetsUseCDN} = 0; to $options{thirdPartyAssetsUseCDN} = 1;.

Database Settings

Search for the code $database_driver. By default the $database_driver is set to MariaDB which is correct unless you installed MySQL. If you installed MySQL, uncomment the MySQL line and comment out the MarisDB line.

We need to set a password that WeBWorK uses when it communicates with the MySQL database. Note that this is not the same as the <mysql root password> which is the unused password we set when securing MySQL. Search for database_password and replace the line

$database_password = "passwordRW";

by

$database_password = 'database_password';

where of course you should replace "database_password" with your own password but do use the single quotes. Remember this password as we will need it below.

WeBWorK sends mail in two instances. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.

To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use localhost. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the From address on the mail message). Edit the lines

$mail{smtpServer} = ;  # e.g. 'mail.yourschool.edu' or 'localhost'
$mail{smtpSender} = ;  # e.g.  'webwork@yourserver.yourschool.edu'

entering the appropriate information. Be sure to use single quotes and NOT double quotes around email addresses otherwise Perl will treat @ as an array variable.

WeBWorK uses the DateTime module. DateTime is supposed to be able to determine the local timezone itself without you having to enter it but this often fails so it is best to just set it here. For a list of timezones recognized by DateTime run the command

timedatectl list-timezones

These timezones are more refined than standard time zone usage in that they include switches to daylight savings time (e.g. some parts of a time zone may make the switch and others may not). For example if your server is in the eastern US, on the list you will see America/New_York and you should enter $siteDefaults{timezone} = "America/New_York"; which is the default. Read the documentation in this section of the the site.conf file for more information on selecting time zones and formatting dates.

Search for $siteDefaults{timezone} and enter your local timezone if it is not correct.

Then save the file and Quit.

The defaults.config file

The defaults.config contains basic defaults for your system. You should not need to change these but if you decide to, you should not change them here since this file will be overwritten when you update WeBWorK. Instead make the change in the localOverrides.conf file using the same syntax as in the defaults.config file.

Custom Themes

If you would like to customize the appearance of WeBWorK, then see Customizing WeBWorK.

Default Header Files

After you have used WeBWorK for awhile, you may want to change the default header files in defaults.config. Search for $webworkFiles{screenSnippets}{setHeader} and $webworkFiles{hardcopySnippets}{setHeader} in localOverrides.config. Settings in the conf and config files affect all WeBWorK courses. You can override any setting in these conf and config files for an individual course by putting the local setting in course.conf.

Check Dependencies

Check Perl Modules

WeBWorK includes a script called check_modules.pl (in the directory /opt/webwork/webwork2/bin) that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.

$ check_modules.pl

Scroll up and look through the listing. It should find everything. If something is missing (flagged by **), look back through these instructions to find where it should have been installed and install it.

Check LaTeX packages

Now we check that all necessary LaTeX packages have been installed. Run the command

$ check_latex

and look for missing packages. If the script displays "Compilation Success!", then all is good!

Set up the webwork database

WeBWorK uses a single database, called webwork, for all courses. We will create the webwork database now.

To do this do the following (before you just copy, paste and hit <Enter> make sure that you replace database_password with the password you set when editing site.conf above):

$ sudo mysql 
MariaDB > CREATE DATABASE webwork;
MariaDB > CREATE USER 'webworkWrite'@'localhost' IDENTIFIED BY 'database_password';
MariaDB > GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO 'webworkWrite'@'localhost';
MariaDB > exit
Bye
$

Serving the Webwork2 Mojolicious App

You now have a choice to make. That is how to serve webwork2. There are two primary choices. Either the app may be served directly via hypnotoad (option 1 below), or it may be proxied via another web server. If your server is dedicated to serving only webwork2, then serving directly via hypnotoad is the simplest choice. (Note that this option does allow for either a customizable root url or a redirect of the root url to another site.) However, if your server will be serving other sites as well then you will need to proxy the app via another web server. For that we provide instructions for serving via apache2 or nginx (options 2 and 3 below). However, another server could be used as well.

All approaches use the webwork2.mojolicious.yml and webwork2.service files. Start by copying the dist files.

$ cd /opt/webwork/webwork2/conf
$ cp webwork2.mojolicious.dist.yml webwork2.mojolicious.yml
$ cp webwork2.dist.service webwork2.service

Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. Near the beginning of the file change the secrets: to whatever you want to change it to, but don't leave it at the default setting. You can choose random characters or a long phrase.

Option 1: Serving Directly via Hypnotoad

Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. At the very end of the hypnotoad: section comment out the line that reads proxy: 1 by inserting a # character at the beginning of the line.

Determine if you are going to be serving securely with SSL certificates or not. If so use port 443 below, otherwise use port 80.

If you are serving securely with SSL certificates, then change listen: at the beginning of the hypnotoad: section to include your ssl certificates. See the examples in the file for the format that is needed. You will also need to make sure that the www-data user has read permissions for the certificate files. This is possibly trickier than you might think: you need the directory path that the certificate and key are in (e.g., .pem files from letsencrypt) to be readable by www-data or whatever your .yml file specifies as the user and group. There is a log by default at /opt/webwork/webwork2/logs/webwork2.log which can often help debugging this step.

If you are not serving securely with SSL certificates, then change listen: at the beginning of the hypnotoad: section to - http://*:80.

Search for the lines

 clients: 1
 workers: 25
 spare: 8

and edit the numbers depending on the amount of RAM available on your server. Look at the recommendations for these settings in the section immediately above these lines in the webwork2.mojolicious.yml file - roughly 10 workers per GB of RAM, with buffer for the OS and the spare; and spare set to approximately 10% of total workers.

Then save the file and Quit.

Install Mojolicious::Plugin::SetUserGroup

By default on Ubuntu ports 80 and 443 can not be bound to by non-root users, and so the hypnotoad server will be started as root so that the needed ports can be bound. However, the server should not be run as root as that is a security vulnerability. So the server will be switched to the www-data user after the ports have been bound. The Mojolicious::Plugin::SetUserGroup module takes care of this. Install it with

$ sudo cpanm --notest Mojolicious::Plugin::SetUserGroup

The --notest flag is needed to skip the module unit tests on Ubuntu 22.04 as those tests fail.

Configure the Webwork2 Systemd Service

There are a few changes to the systemd service configuration needed for this option. Edit /opt/webwork/webwork2/conf/webwork2.service with your preferred text editor. Comment out the lines that read

User=www-data
Group=www-data
Environment="MOJO_REVERSE_PROXY=1"

by inserting a # character at the beginning of each line.

Then save the file and Quit.

Optional Configuration Details

Next determine where you want the root url to go, i.e., the location http[s]://yoursite.edu/.

If you want to display fixed html content, then execute

$ cp /opt/webwork/webwork2/htdocs/index.dist.html /opt/webwork/webwork2/htdocs/index.html

and edit the copied file by adding your custom content.

If you want to redirect to another site, then edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml, uncomment the server_root_url_redirect: setting, and change that setting to point to the desired site.

If you are serving securely with SSL certificates, then you will most likely want to redirect unsecure connections to port 80 to secure connections on port 443. To make this happen add the line - http://*:80 below the line - https://*:443?... in the listen: part of the the hypnotoad: section, and change redirect_http_to_https: 0 to redirect_http_to_https: 1 in the file /opt/webwork/webwork2/conf/webwork2.mojolicious.yml.

Option 2: Serving via Proxy by Apache2

First install the apache2 server with

$ sudo apt install apache2

Note that this guide does not cover basic site configuration of the apache2 server.

Webwork2 ships with an apache2 configuration file that needs to linked into your apache2 configuration process. Create a copy of the dist file with

$ cp /opt/webwork/webwork2/conf/webwork2.apache2.4.dist.conf /opt/webwork/webwork2/conf/webwork2.apache2.4.conf

and link it into your apache2 configuration process with

$ sudo ln -s /opt/webwork/webwork2/conf/webwork2.apache2.4.conf /etc/apache2/conf-enabled/webwork2.conf

If you do not have ssl certificates to serve with https, then edit /opt/webwork/webwork2/webwork2.apache2.4.conf, and change RequestHeader set X-Forwarded-Proto "https" to RequestHeader set X-Forwarded-Proto "http".

Additional apache2 modules are needed to proxy webwork2. Enable these with

$ sudo a2enmod proxy proxy_http headers

Next we will make a few changes to Apache's default configuration. We need to edit two files. First we will save copies of the original files.

$ cd /etc/apache2/
$ sudo cp apache2.conf apache2.conf.bak
$ cd /etc/apache2/mods-available/
$ sudo cp mpm_event.conf mpm_event.conf.bak

Edit apache2.conf

$ sudo nano /etc/apache2/apache2.conf

Search for the line

Timeout 300

and replace it by

Timeout 1200 

Then save the file and quit.

Edit mpm_event.conf

$ sudo nano /etc/apache2/mods-available/mpm_event.conf

Search for the lines

   MaxRequestWorkers        150
   MaxConnectionsPerChild   0

Which occur under <IfModule mpm_event_module> and replace them by

   MaxRequestWorkers        10
   MaxConnectionsPerChild   50

where you should set MaxRequestWorkers depending on what is needed for your server. A good rule of thumb is 5 MaxRequestWorkers per 1 GB of memory available on the server. Note that for busy servers, you should observe your memory usage and adjust the above settings as necessary. Also make sure MaxSpareThreads is not set too high.

Then save the file and quit.

Now restart apache2 so that changes to the configuration take effect.

$ sudo systemctl restart apache2

The apache2 process is controlled with systemctl. If the apache2 configuration is changed, then you will need to restart apache2 in order for those changes to take effect as was done above. In addition you can stop and start the apache2 process with

$ sudo systemctl stop apache2
$ sudo systemctl start apache2

You can also obtain more information about the running service with

$ systemctl status apache2

Sometimes to determine problems with the apache2 process it is helpful to view the apache2 error log. The log is saved in the file /var/log/apache2/error.log.

Option 3: Serving via Proxy by Nginx

First install the Nginx server with

$ sudo apt install nginx

At this point this guide does not cover basic site configuration. Ubuntu has a default configuration file located at /etc/nginx/sites-available/default that you can start with for this. (Nginx documentation recommends using a file in /etc/nginx/conf.d instead.) In any case make note of which file you are using for the following. This will be referred to as "your site's Nginx configuration file."

Webwork2 ships with an Nginx configuration file that needs to be included in your Nginx configuration. Create a copy of the dist file with

$ cp /opt/webwork/webwork2/conf/webwork2.nginx.dist.conf /opt/webwork/webwork2/conf/webwork2.nginx.conf

Edit your site's Nginx configuration file to include this file. In your configuration file find the primary server section, and add the line include /opt/webwork/webwork2/conf/webwork2.nginx.conf; to the end of the section. You will need to determine which server section is the correct one to use if you have multiple such sections in the file.

Restart the nginx process for that change to take effect.

$ sudo systemctl restart nginx

The nginx process is controlled with systemctl. If the nginx configuration is changed, then you will need to restart nginx as done above. In addition you can stop and start the nginx process with

$ sudo systemctl stop nginx
$ sudo systemctl start nginx

You can also obtain more information about the running service with

$ systemctl status nginx

Sometimes to determine problems with the nginx process it is helpful to view the nginx error log. The log is saved in the file /var/log/nginx/error.log.

Install Favicon for Options 2 and 3

Copy WeBWorK's icon file favicon.ico to Ubuntu's html directory.

$ sudo cp /opt/webwork/webwork2/htdocs/favicon.ico /var/www/html

Enable and start the Webwork2 Systemd Service

Next set up the systemd service that will control the webwork2 app. Execute the following to enable and start the service.

$ sudo systemctl enable /opt/webwork/webwork2/conf/webwork2.service
$ sudo systemctl start webwork2

At this point webwork2 is now running, and you should be able to open your browser to http://yoursite.edu/webwork2 or https://yoursite.edu/webwork2.

Note that anytime you make changes to the webwork2 configuration files you will need to restart the app in order for those changes to take effect. This can be done by executing

$ sudo systemctl restart webwork2

In addition you can stop and start the webwork2 app with

$ sudo systemctl stop webwork2
$ sudo systemctl start webwork2

Set Up the Webwork2 Job Queue

Some long running processes are not directly run by the webwork2 app. Particularly mass grade updates via LTI and sending of instructor emails. Instead these tasks are executed via the webwork2 Minion job queue. If the users of your system will be utilizing either of those features, then you will need to set up the webwork2 job queue. If those features will not be utilized by the users of your system, then you can skip this section.

Install Dependencies

The libminion-backend-sqlite-perl package installed above depends on libmojo-sqlite-perl which contains version 3.008 of the Perl module Mojo::SQLite. Unfortunately, there is an issue with that version on Ubuntu 22.04 that prevents the Minion SQLite backend from functioning correctly. So version 3.002 needs to be installed from CPAN instead.

First install additional Ubuntu packages that are needed for this with

$ sudo apt install libextutils-config-perl libextutils-installpaths-perl libextutils-helpers-perl

Then downgrade Mojo::SQLite with the command

$ sudo cpanm --notest Mojo::SQLite@3.002

Note that the --notest flag is needed as the unit tests that are executed by default also fail.

Enable and start the Webwork2 Job Queue Systemd Service

Copy webwork2-job-queue.dist.service to webwork2-job-queue.service with

$ cd /opt/webwork/webwork2/conf
$ cp webwork2-job-queue.dist.service webwork2-job-queue.service

Then execute the following to start the job queue

$ sudo systemctl enable /opt/webwork/webwork2/conf/webwork2-job-queue.service
$ sudo systemctl start webwork2-job-queue

Note that you can start, stop, and restart the job queue with the following commands:

$ sudo systemctl start webwork2-job-queue
$ sudo systemctl stop webwork2-job-queue
$ sudo systemctl restart webwork2-job-queue

It is worth checking to make sure the webwork2-job-queue has started properly. If anything is wrong, it'll quietly just hang, and then most of the courses will run fine, except certain things like mass grade updates, which will just never run.

$ sudo systemctl status webwork2-job-queue

Even though the webwork2-job-queue.service file specifies user www-data and group www-data, and even if permissions are set appropriately as above (re: logs directory), if you're doing an upgrade-in-place, you might end up in a situation where the www-data user can't write to webwork2.log, and then the job queue will fail. The above status check will indicate this, and you can then double-check permissions on the log directory, and make sure that the files are writeable by www-data.

Test your configuration

Test the /webwork2 location by visiting http://yourserver.yourschool.edu/webwork2. You should see the WeBWorK home page with no courses listed. Actually the directory /opt/webwork/courses/ does contain the modelCourse but the modelCourse is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason /opt/webwork/courses/modelCourse/ contains a file named hide_directory and so the modelCourse is not visible.

If Something is Wrong

If something is wrong one of the first things to check is that the config files have been edited correctly. A quick way to check this is to do a diff between the edited and distributed versions and check that diff reports the changes you made and only those. You may also want to check the webwork2 app log. Errors and other information from the running app will appear here. The webwork2 app log is saved in the file /opt/webwork/webwork2/logs/webwork2.log.

$ cd /opt/webwork/webwork2/conf/
$ diff site.conf site.conf.dist
$ diff localOverrides.conf localOverrides.conf.dist
$ tail /opt/webwork/webwork2/logs/webwork2.log

If something is wrong and you fix it, you will have to restart webwork2 for the changes to take effect

$ sudo systemctl restart webwork2

If webwork2 is proxied via another web server, then you may also need to examine the configuration files and log files for the web server as well. If changes are made to the web servers configuration file, then the web server will need to be restarted.

Create the admin Course

Course Administration gives information about creating courses. Here we will give explicit instructions for doing this. (You may need to become root or use sudo to execute some of these commands.)

$ cd /opt/webwork/courses
$ /opt/webwork/webwork2/bin/addcourse admin --users=adminClasslist.lst
$ sudo chown -R www-data:www-data admin

where the last line makes the course admin and its subdirectories owned by the Apache server and readable/writeable by the wwadmin user.

Now go to http://yourserver.yourschool.edu/webwork2 and should see the WeBWorK home page with Course Administration listed at the top. Click on it and login with Username admin and Password admin . This first thing you should do is register your new WeBWorK installation. It's quick and easy, just click on Register. IMPORTANT The next thing you should do is click on User Settings and change admin 's password to something more secure than admin .

Unless you choose otherwise, users with admin privileges in the admin course (i.e. WeBWorK administrators) will automatically be added to new courses with admin privileges and the same password as in the admin course. Initially the only such user is admin (hopefully you are not confused by the fact that the course admin has a user named admin). It's usually convenient make yourself a WeBWorK administrator. To do this (assuming you are logged in as admin to the admin course at http://yourserver.yourschool.edu/webwork2/admin )

  1. Click on Classlist Editor in the left panel
  2. Click the Add tag and click Take Action!
  3. Enter the appropriate information (you can use your Login Name as the Student ID if you want and also you can leave the last three items blank) and click Add Students
  4. Click on Classlist Editor in the left panel again
  5. When you enter a new student, by default their Student ID is used as their password. We'll change this now.
  6. Select yourself with a check mark and click the Password tag and click Take Action!. (Note as a safely mechanism you can not change the password for the user you are logged in as, currently admin, this way)
  7. Enter the password and then click Take Action!
  8. Finally give yourself admin privileges by selecting yourself with a check mark, clicking the Edit tag and then clicking Take Action! (or by just clicking on the "pencil" next to your login name which is a much faster way to edit classlist data for a single user)
  9. Now at the far right change Permission Level from student to admin
  10. Then click Take Action!

At some point you will probably want to hide the admin course so that it is not listed on the WeBWorK home page. As we noted above the modelCourse, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The modelCourse is very useful as a model (hence its name) for setting up other courses. The admin course is used for administering WeBWorK and even though regular users can not log into it (you did change the admin password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes. To hide (or unhide) a course select Hide Courses in the admin course and follow the directions. When hidden a course will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the admin course using the URL http://yourserver.yourschool.edu/webwork2/admin but you will not see a link for it on the WeBWorK home page http://yourserver.yourschool.edu/webwork2 .


Now go to http://yourserver.yourschool.edu/webwork2 and no course will be listed.

Check for and Install Hotfixes

The following commands show you how to check for and install bug fixes. Important Note: These commands check and retrieve the main branch which gives the latest stable release of the software package (webwork2, pg, etc.) with bug fixes. If a stable release newer than 2.18 exists for webwork2 and/or pg, that will be checked and retrieved which is probably not what you want. Please check before updating. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/main/VERSION and https://github.com/openwebwork/pg/blob/main/VERSION.

To check if there are bug fixes, do the following.

Update the webwork2 code

First we check for updates to the webwork2 code:

cd /opt/webwork/webwork2/
git remote show origin

This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run

git pull origin

and restart webwork2.

Update the pg code

Now check for updates to the pg code:

cd /opt/webwork/pg/
git remote show origin

This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run

git pull origin

and restart webwork2.

Restart webwork2

Important: After updating either webwork2 or pg, you have to restart the webwork2 app with

$ sudo systemctl restart webwork2

Update the OPL

The following assumes you have already installed the OPL. For that see #Install the Open Problem Library below. Now check for updates to the Open Problem Library (OPL):

$ cd /opt/webwork/libraries/webwork-open-problem-library
$ git remote show origin

This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date and you want to update, run:

$ git pull origin
$ OPL-update

Important Note: The OPL contains over 37,000 problems and if one new problem is added, the above will report the OPL is out of date. I would suggest you update the OPL maybe once or twice a semester. Also the version of the OPL contained in the WW 2.18 Virtual Machine Image and in the WW 2.18 Amazon Machine Image is current as of August 1, 2023.

Updating the OPL is pretty much risk free since changes usually involve only a relatively small number of individual problems and the vast majority of problems remain unchanged. Updating the OPL does not require restarting webwork2.

Install the WeBWorK Problem Libraries

Before we create a real course we will install the WeBWorK Problem Libraries.

Install the Open Problem Library

The Open Problem Library 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 load a database for searching it.

Run the OPL-update script which will download the OPL metadata release and checkout the corresponding tag in the library as needed for the Library Browser in WeBWorK. Since this is a new installation, we do not have any OPL statistics to upload (see OPL_Problem_Statistics), so we run the command:

$ SKIP_UPLOAD_OPL_STATISTICS=1 OPL-update

If at some time in the future you want to upgrade the Problem Library, the process is easy, see Updating the OPL. Note that this is something you should do fairly often so that your library is up to date with new problems and bug fixes for old ones.

Set up access to the Contrib directory

The Contrib directory contains contributions to the OPL that may not have been formally accepted into the main collection of OPL problems. This may be because the contribution is recent and has not yet been reviewed or because the problems are not properly tagged as is the case with the CAPA problem collection. It also contains the original versions of problems that have been accepted into the OPL (the idea being that the original authors maintain control of problems in the Contrib directory but problems in the OPL are controlled by the editors).

There should be a link named Contrib in the directory

/opt/webwork/courses/modelCourse/templates/

so that when courses are created copying templates from the modelCourse, the Contrib directory will be available. A button in the Library Browser which gives access to problems in the Contrib directory will be available for all courses with this link. We recommend you keep this setting.

However, if you only want this for individual courses, not all courses then remove the link in the modelCourse above. Then after creating a course, for example after creating myTestCourse below, do the following

$ cd /opt/webwork/courses/myTestCourse/templates/
$ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib Contrib

to enable access to Contrib for the course. For other courses change myTestCourse to the course id.

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 OPL Directory button. But you can follow this example if you want to create button(s) for direct access to other sub libraries.

First we need to edit localOverrides.conf one last time

$ cd /opt/webwork/webwork2/conf
$ nano localOverrides.conf

Search for courseFiles{problibs} and scroll down several lines to the lines

#      rochesterLibrary => "Rochester",
# 	unionLibrary     => "Union",

Uncomment these lines (i.e. remove the #) so they become

      rochesterLibrary => "Rochester",
      unionLibrary     => "Union",

Then save the file and quit.

We next put links to the Rochester and Union Libraries in the modelCourse so that when we create courses copying templates from the modelCourse, these libraries will be available. Skip this step if you usually only want to use Open Problem Library. Note that the Rochester, Union and other libraries are contained in the OPen Problem Library and are accessible from there under the OPL Directory 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/
$ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Union unionLibrary
$ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Rochester rochesterLibrary

If you want to put another library into the modelCourse, just do the analogous thing. If you just want the additional library in a particular course, add the link in the templates directory of that course. If you look in the directory /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/ you might find other libraries that are not yet listed in global.conf and these can be added in the same way as the Rochester and Union libraries. Finally if you add a library with non standard symbols in the name (e.g. uva-statLibrary) you have to use single quotes when adding it to global.conf, e.g.
         'uva-statLibrary' => "UVA-Stat",
It's easier to just avoid such names.

Install and Set Up the CAPA Library

This step is optional. It installs and sets up the CAPA Library, which is a library of physics problems.

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 put the link in the modelCourse. Actually this link, called capaLibrary, has already been added to

/opt/webwork/courses/modelCourse/templates/

so no action on your part is required.

If you just want to do this for individual courses, not all courses then remove the link capaLibrary in the modelCourse above, and then do the following. We don't have any yet. But for example after creating myTestCourse below, to set up access to the CAPA Library from myTestCourse, do the following

$ cd /opt/webwork/courses/myTestCourse/templates/
$ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/   capaLibrary

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 Library Browser and click on the CAPA button.

Create Your First Actual Course

Since we have edited site.conf and localOverrides.conf and these are critical files, it would be a good idea to run

$ cd /opt/webwork/webwork2/conf
$ diff site.conf site.conf.dist
$ diff localOverrides.conf localOverrides.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 these files you must restart the webwork2 app in order for these changes to take effect. Do this with

$ sudo systemctl restart webwork2

Now log into the admin course ( http://yourserver.yourschool.edu/webwork2/admin or, if you have not hidden the admin course, click on Course Administration on WeBWorK's home page http://yourserver.yourschool.edu/webwork2/ ) as yourself or admin and

  1. click on Add Courses
  2. For Course ID enter myTestCourse
  3. For Course Title enter My Test Course
  4. Enter your institution
  5. Leave Add WeBWorK administrators to new course checked
  6. Add an additional instructor if you wish
  7. Copy templates from: modelCourse (the default action)
  8. Leave Also copy simple configuration file checked
  9. Click on Add Course
  10. Click Log into myTestCourse

and log in either as admin or yourself (if you added yourself as an additional instructor above).

At some point you will probably want to "hide" myTestCourse 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 WeBWorK app error log which is located at /opt/webwork/webwork2/logs/webwork2.log and/or the Apache error log which is located at /var/log/apache2/error.log and/or the nginx error log located at /var/log/nginx/error.log.

Click on Hmwk Sets Editor on the Main Menu. Then select Import, select setDemo.def from the Import from where drop down list and select all current users from the assigning this set to drop down list. Then hit Import

Now click on Homework Sets on the Main Menu and click on Demo. Then look at the problems. Mathematical equations should be displayed nicely by MathJax (right click on the equation for info). You can also display equations as images but this is not recommended.

Note that since you probably used "admin" to login you have Permission Level "admin" so things look a bit more complicated than if you were just a regular professor with Permission Level "professor". In particular any time you view a problem, you have the option to "Edit tags" which you probably do not want to do. If this bothers you, login as a professor (see below).

Continue looking at problems to see if everything is working properly.

Next click on Problem List to bring back the Problem List Page and click on Download PDF .... The page is complicated because you are an admin so you see the professor view (students see a very simple page) but you can just scroll to the bottom and click on Generate hardcopy for selected users and selected sets. If you get an error, then look at the various log files that are linked to on the output page (normally these files are removed if there are no errors). If you want to preserve these temporary files, then set perserve_temp_files to 1 in the file /opt/webwork/webwork2/conf/webwork2.mojolicious.conf and restart the webwork2 service. Remember to change preserve_temp_files back to 0 and restart the webwork2 service again or you will be saving a lot of unnecessary files. You can find these temporary files in /opt/webwork/webwork2/tmp/, then look under your course, hardcopy, and user. You will have to switch to being the root user to access the final subdirectory containing the tmp files.

Another thing to do is to use Email on the Main Menu. 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 Send Email 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 Library Browser on the Main Menu. Click Open Problem Library (actually it should already be selected so it will be greyed out) and select a Subject, Chapter and Section and then hit View Problems. 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. Note that if you just happen to view some statistics problems that require the R server, you will get errors (since we have not installed R --- at least not yet).

Note: if when using the Library Browser you find that after selecting a Subject, you can not select a Chapter (and usually an error toast will be shown), the most common reason is that $server_root_url has not been set "correctly" in the /opt/webwork/webwork2/conf/site.conf file. A common error is to use forget http:// or to use http:// when you should use https:// or to just have the wrong domain name or ip address. But sometimes "localhost" will work when the correct ip address or url will not, for example in situations when you are using a virtual machine as your host.

If all the above tests work, you can be pretty confident that WeBWorK is working properly.

Go back to Hmwk Sets Editor on the Main Menu. Then select Import, select setOrientation.def from the from drop down list and select all current users from the assigning this set to drop down list. Then hit Take Action!. Then go through the Orientation problems. This is a good first set to use for introducing students to WeBWorK. Also you can Import set0.def and setMAAtutorial.def and look through those problems. Note that most of these sets date from the early days of WeBWorK in the 1990's and the problems they contain, while they still work, are not examples of current good programing practices. For current programing methods, look at e.g. https://webwork.maa.org/wiki/Category:PGM. Further, Problem 12 in setMAAtutorial (file htmllinksexample.pg) contains a simple error which is typical of errors you might make in authoring your own problems. WeBWorK tries to tell you what the error is and you can use the Edit button to edit and save the problem. Problem 2 in set0 (file prob1a.pg) may contain more subtle errors. The Open Problem Library (OPL) contains over 37,000 problems the vast majority of which are error free.

If you are new to WeBWorK or even if you are a pro, 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 or admin interfaces. Also for the same reason you should probably add a professor to myTestCourse and log in as that professor to see what the professor interface looks like.

Click on Classlist Editor on the Main Menu. Then select Add, for "Add how many students?" pick 2 and hit Take Action!. Then add two students, say

  • Last Name "Smith", First Name "Jane" , Student ID "jsmith" and Login Name "jsmith"
  • Last Name "A", First Name "Prof" , Student ID "profa" and Login Name "profa"

and make sure to select all sets to assign them to both of them. Then hit Add Students.

Now we make "profa" a professor. Again click on Classlist Editor on the Main Menu. The fast way is to click on the "pencil" by "profa", set the "Permission Level" to "professor" and hit Take Action!.

Jane Smith's initial password will be her Student ID jsmith. Now login as Jane Smith and play around a little.

Prof A's initial password will be her Student ID profa. You should also login as Prof A and play around a little.

You can also add "practice users" and login as one of those to see how you can grant partial access to your course for practice or other reasons (e.g. auditors who don't want to be graded). To do this Click on Classlist Editor, select Import, select the "demoCourse.lst" (the only classlist available at this point) and hit Take Action!.

More House Keeping

Hide the admin and myTestCourse courses

Log out of myTestCourse if you are logged in and go to the WeBWorK Welcome page. Click on Course Administration and login as admin with the new admin password you set for the admin course. Select "Hide Inactive Courses" and select the courses you want to hide and hit "Hide Courses". If you go back to the WeBWorK Welcome page, you will see no courses listed. You can still access these courses directly by

http://yoursite.edu/webwork2/admin 
http://yoursite.edu/webwork2/myTestCourse 

where of course you should use your actual url.

Replace the default landing page

If serving webwork2 via a proxy by another web server, then you probably should replace /var/www/html/index.html with a page which redirects to the webwork course list at your site. If serving webwork2 directly, then the same can be accomplished by editing /opt/webwork/webwork2/htdocs/index.html (unless you are using the server_root_url_redirect: setting instead). Something like the following should work:

<html>
<head>
  <meta http-equiv="Pragma" content="no-cache">
  <meta http-equiv="Refresh" content="0;url=https://mysite.mydomain.edu/webwork2/">
  <title>WeBWorK site - redirects to main page</title>
</head>
<body style="text-align: center;">
  You probably want to use the
  <a href="https://mysite.mydomain.edu/webwork2/">the WeBWorK list of courses page</a>
</body>
</html>

The institution logo (which is the MAA logo by default) appears on every WeBWorK page. You can replace with you own logo by doing the following. We took these directions verbatim from Alex Jordan's Forum post https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5642.

All you need to do is add lines like these to a config file like localOverrides.conf:

$institutionLogo = 'myimage'; $institutionURL = 'URL for target if a user clicks on the image'; $institutionName = 'Name of the target, to be used in alt text';

myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.

The easiest way to do this is to search for the lines

# The institution logo should be an image file in the theme's images folder
#$institutionLogo = 'my_school_logo.png';
#$institutionURL  = 'http://www.myschool.edu';
#$institutionName = 'My University';

in /opt/webwork/webwork2/conf/localOverrides.conf, remove the #'s from the last three lines and enter your information. If you want to just make the change for an individual course, copy the code and put it in /opt/webwork/courses/Course_Name/course.conf.

Optional Configurations

You should definitely consider implementing the following optional configurations.

Option A configures the server so that access to WeBWorK will be through an encrypted connection (SSL) with an https: URL.

Option B installs and configures the R server for statistical computing. Many statistics and probability problems (mostly contributed by faculty at the University of British Columbia) require this.

Option C sets up log rotation for WeBWorK's timing log.

Implement Option A (SSL)

Option A configures the server so that access to WeBWorK will be through an encrypted connection (SSL) with an https: URL. Note that TLS is the successor protocol to SSL and is used everywhere. So that when we and others use the more common acronym SSL, we really are talking about TLS.

Note that there are very explicit instructions for setting up an SLL connection using the WeBWorK AMI image, Certbot, and Hypnotoad at WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image#Set_up_WeBWorK_to_use_SSL which may be useful.

First we have to obtain an official SSL certificate or generate a self-signed one which can be used for testing purposes. If students will be using your server, it is better to obtain an official SSL certificate since using a self-signed certificate with cause warning messages to be displayed when students connect to the server.

Obtain an Official SSL Certificate

Talk to the networking group on your campus about obtaining an official certificate. You can find information on the net about certificate providers, e.g. http://www.sslshopper.com/certificate-authority-reviews.html . Certbot (https://certbot.eff.org/) which uses Let's Encrypt certificates (https://letsencrypt.org/) is a good option if you are not using your organization's official certificates.

The certificate goes in /etc/ssl/certs/ and the key file goes in /etc/ssl/private/.

Use a self-signed Certificate

First we need to install a package which is needed for openssh-server to generate a self-signed certificate.

$ sudo apt-get install ssl-cert

Then run

$ sudo make-ssl-cert generate-default-snakeoil --force-overwrite

This creates a certificate stored at

/etc/ssl/certs/ssl-cert-snakeoil.pem

and a private key at

/etc/ssl/private/ssl-cert-snakeoil.key

I believe this certificate is only valid for 365 days. You can generate a new certificate with the same command.

In the instructions below we will use the provided self-signed certificate (ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key) but you can also generate your own using openssh following instructions on the web. As we said above, for a production server, you should really use an official certificate.

Set up the Server to use SSL

Now we need to set up the server to use the SSL certificates. Choose your deployment option below and follow the directions for that option.

Our self-signed certificate and key files are named /etc/ssl/certs/ssl-cert-snakeoil.pem and /etc/ssl/private/ssl-cert-snakeoil.key. If you are using official files, use their file names instead. Additional configuration may also be needed in some cases. Instructions for doing so are beyond the scope of this document. You might look at https://docs.mojolicious.org/Mojo/Server/Daemon#listen for direct deployment via hypnotoad (you could also try using https://metacpan.org/pod/Mojo::ACME for letsencrypt), https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-ubuntu-22-04 for apache2, or https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-22-04 for nginx.

Set up Hypnotoad to use SSL (Option 1)
The only thing that needs to be done is to tell hypnotoad where the certificates are.  For this edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml and in the hypnotoad: section change
listen:
 - http://*:8080

to

listen:
 - https://*:443?cert=/etc/ssl/certs/ssl-cert-snakeoil.pem&key=/etc/ssl/private/ssl-cert-snakeoil.key

Make sure that the files are readable by the webwork2 app.

$ sudo chown www-data /etc/ssl/certs/ssl-cert-snakeoil.pem /etc/ssl/private/ssl-cert-snakeoil.key

The webwork2 app needs to be restarted for this to take effect, but we will delay that until a bit later. Go to the check site.conf section below.

Set up Apache to use SSL (Option 2)

First we enable the mod_ssl module

$ sudo a2enmod ssl

Now we have to configure Apache to use SSL.

$ cd /etc/apache2/sites-available/
$ sudo cp default-ssl.conf default-ssl.conf.bak
$ sudo nano default-ssl.conf

Search for the lines

SSLCertificateFile      /etc/ssl/certs/ssl-cert-snakeoil.pem
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key

and replace ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key by the names of your certificate. Since in these instructions we are using ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key, we can just leave the lines as is.

Then save the file and quit. And enable default-ssl.conf

$ sudo a2ensite default-ssl.conf

Finally we restart Apache

$ sudo systemctl restart apache2

and test things. Connect to https://yourserver.yourschool.edu/webwork2/myTestCourse . If you are using the snakeoil certificates you will see warning messages (e.g. NET::ERR_CERT_AUTHORITY_INVALID) and you will be asked to accept the risk. After you do so things should work just as before except that the connection will be via https.

Redirect http requests to https

Assuming that everything is working, the next 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/.

$ cd /etc/apache2/sites-available
$ sudo cp 000-default.conf 000-default.conf.bak
$ sudo nano 000-default.conf

In the

<VirtualHost *:80>

section just under the line

DocumentRoot /var/www/html

add the line

Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2

where of course you should edit yourserver.yourschool.edu appropriately. Then save the file and quit. Restart Apache

$ sudo systemctl restart apache2

and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.edu/webwork2/.

Set up Nginx to use SSL (Option 3)

You should identify the correct file to use for your system if you have already created an Nginx site configuration file. If you have not then a good starting point is to copy /etc/nginx/sites-available/default to /etc/nginx/conf.d/default-ssl.conf and modify that. Add the lines

ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;

to the file after the listen lines near the beginning of the server section. The contents of the file should now look something like the following.

server {
  listen 443 ssl default_server;
  listen [::]:443 ssl default_server;

  ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
  ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;

  root /var/www/html;

  index index.html index.htm;

  server_name yourserver.yourdomain.edu;

  location / {
    # First attempt to serve request as file, then
    # as directory, then fall back to displaying a 404.
    try_files $uri $uri/ =404;
  }

  include /opt/webwork/webwork2/conf/webwork2.nginx.conf;
}

Restart Nginx for this to take effect.

$ sudo systemctl restart nginx

You should now be able to open the url https://yourserver.yourdomain.edu/webwork2 in a browser.

Redirect http requests to https

Add the following to the beginning of your nginx site configuration file.

server {
  listen 80 default_server;
  listen [::]:80 default_server;
  server_name yourserver.yourdomain.edu;
  return 301 https://yourserver.yourdomain.edu$request_uri;
}

Restart Nginx for this to take effect.

$ sudo systemctl restart nginx

You should now be able to open the url http://yourserver.yourdomain.edu/webwork2 in a browser and it will automatically be redirected to https://yourserver.yourdomain.edu/webwork2.

Check site.conf

This is important. We have to check the value of $server_root_url in webwork2/conf/site.conf to make sure it uses https (so it should read e.g. https://yourserver.yourschool.edu). If you don't do this, your may run into strange problems in the Library Browser. To check, open the Library Browser, select a subject and then click on the chapter area. If you see a drop down list of chapters, things are working properly.

Now we check and edit if necessary site.conf

cd /opt/webwork/webwork2/conf
nano site.conf

In the line

$server_root_url = ...

replace http by https if necessary. Then save the file, quit and restart webwork2

sudo systemctl restart webwork2

Implement Option B (Rserve)

Here we will install and configure the R server for statistical computing. Many statistics and probability problems (mostly contributed by faculty at the University of British Columbia) require this.

See the documentation (from which we have borrowed heavily) R_in_WeBWorK for more detailed information.

Install the R server

$ sudo apt install r-cran-rserve

and check that R is running

$ R

You should see something very similar to

R version 4.1.2 (2021-11-01) -- "Bird Hippie"
Copyright (C) 2021 The R Foundation for Statistical Computing
...
Type 'q()' to quit R.

>

and then quit

> q()
Save workspace image? [y/n/c]: n

Configure Webwork with the location of the R server

We have to edit the localOverrides.conf file.

$ cd /opt/webwork/webwork2/conf
$ nano localOverrides.conf

Search for the line

#$pg{specialPGEnvironmentVars}{entryAssist} = 'MathView';

and under that line add the following

################################################################################
#location of the R server
################################################################################
$pg{specialPGEnvironmentVars}{Rserve} = {host => 'localhost'};

Then save the file and Quit.

Set up Rserve to run as a daemon at system boot

This is somewhat complicated. I'm basically following instructions from https://github.com/geordielad/rserve-systemd-unit

First we create a user with limited privileges to run rserve.

$ sudo adduser rserveuser --system --shell=/bin/false --no-create-home --disabled-password --disabled-login

Next we create a file to automatically start Rserve

$ cd
$ nano rserve.service

Now copy and paste the following code into nano

[Unit]
Description=Rserve

[Service]
Type=forking
PIDFile=/var/run/rserve/rserve.pid

# Define runtime directory
RuntimeDirectory=rserve
RuntimeDirectoryMode=750

User=rserveuser
Group=nogroup

ExecStart=/usr/bin/R CMD Rserve --quiet --vanilla --RS-pidfile /var/run/rserve/rserve.pid

[Install]
WantedBy=multi-user.target

and then save the file and quit. Change the owner to root, move the file to the proper location and register it.

$ sudo chown root:root rserve.service
$ sudo mv rserve.service /etc/systemd/system
$ sudo systemctl daemon-reload

Next we enable the service to start when the system starts

$ sudo systemctl enable rserve.service

and finally set up some needed links

$ cd /usr/lib/R/bin/
$ sudo ln -s ../site-library/Rserve/libs/Rserve
$ sudo ln -s ../site-library/Rserve/libs/Rserve.dbg

Test that things are working properly

First start Rserve manually

$ sudo systemctl start rserve

and run

$  sudo lsof -i -P -n | grep LISTEN

and you should see that Rserve is listening on port 6311

Next test that WeBWorK problems using R run properly. In WeBWorK, click on Library Browser on the Main Menu. Then click Open Problem Library (actually it should already be selected so it will be greyed out). Now select "Statistics" as Subject, "Bayesian inference" as Chapter and "Posterior distribution" as Section and then hit View Problems. Also test a problem with graphics, e.g. select "Statistics" as Subject, "Hypotheses tests" as Chapter and "One-way ANOVA" as Section and then hit View Problems.

If the problems display with no error messages, all should be well (for the graphics problem, look at Library/UBC/STAT/STAT300/hw06/stat300_hw06_q01.pg). To be totally sure, click on the "eye" (Try it) in the upper right corner and test the problem. If there are no error messages, congratulate yourself. Everything works.

Finally reboot your server (to test that the Rserve starts automatically on boot up) and run

$ sudo systemctl status rserve.service

to check that all is well and just to be redundant

$  sudo lsof -i -P -n | grep LISTEN

again. Now we are sure that Rserve automatically starts when the system is booted.

Loading additional modules

This step should not be necessary unless you are writing or using WeBWorK problems that need additional resources beyond what is loaded by default. An example is using R to compute complex eigenvalues which requires the Math::Complex module (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5577). The error message in such a case would be similar to

Can't locate object method "make" via package "Math::Complex" (perhaps you forgot to load "Math::Complex"?) at /usr/share/perl/5.30/Math/Complex.pm line 329
   Died within Math::Complex::cplx called at line 351 of /usr/local/share/perl/5.30.0/Statistics/R/IO/QapEncoding.pm
   from within Statistics::R::IO::QapEncoding::decode called at line 236 of /usr/local/share/perl/5.30.0/Statistics/R/IO/Rserve.pm
   from within Statistics::R::IO::Rserve::eval called at line 26 of [PG]/lib/Rserve.pm
   from within Rserve::try_eval called at line 146 of [PG]/macros/RserveClient.pl
   from within main::rserve_eval called at line 40 of (eval 4456)

First note that the required module must be installed on your server. The Math::Complex module already is which we can see by running the command

perl -MMath::Complex -e 'print "installed!\n"'

which returns installed!. If it were not installed you would see at lot of gibberish. In general to test if a Perl module is installed and working on your system, issue the above command, replacing Math::Complex with the name of the module. To install additional Perl modlues , see Installation of Other Perl Modules with cpanm above.

We need to load Math::Complex into WeBWorK's safe compartment. For this we have to edit the localOverrides.conf file.

$ cd /opt/webwork/webwork2/conf
$ nano localOverrides.conf

Now search for the line

# Additional PG modules

and under the line

#push (@{${pg}{modules}}, [qw(TikZ_Image2)]);

add the line

push @{$pg{modules}}, [qw(Math::Complex)];

You can add as many modules as you need this way.

Then save the file and Quit.

Implement Option C (Logrotate)

Here we will set up log rotation for WeBWorK's timing log and webwork2 app log which can grow huge especially if you have a large number of users. The timing.log gives timing information on every action in WeBWorK (see WeBWorK_performance) and can be used to assess the performance of your server. The webwork2.log file contains webwork2 app log output including errors that can be useful for debugging issues.

Create a WeBWorK configuration file for Logrotate

Logrotate’s configuration files are located in /etc/logrotate.d. Now we create one for WeBWorK.

$ sudo nano /etc/logrotate.d/webwork

Now copy and paste the following code into nano

/opt/webwork/webwork2/logs/timing.log {
su www-data www-data
weekly
missingok
rotate 15
compress
delaycompress
notifempty
}

/opt/webwork/webwork2/logs/webwork2.log {
su www-data www-data
weekly
missingok
rotate 15
compress
delaycompress
notifempty
copytruncate
}

and then save the file and quit.

There is one additional step that is needed if you are serving directly via hypnotoad. In that case the webwork2 application initially starts as the root user, and then switches to the www-data user, and the webwork2.log file is created by the root user before the switch is made. So the file's owner and group need to be fixed. You can do this by executing

$ sudo chown www-data:www-data /opt/webwork/webwork2/logs/webwork2.log

The backup will be done weekly and we are keeping 15 weeks (approximately one semester) worth of logs. The most recent backup will not be compressed but all older ones will be. We are not explicitly creating a new timing.log file because WeBWorK will automatically create one if it's missing. If you want to check that it works you can run logrotate with the configuration file (make sure you have done something with WeBWorK so that the timing.log is not empty):

sudo logrotate -f /etc/logrotate.d/webwork

Then if you look in /opt/webwork/webwork2/logs, you should see the following files

webwork2.log
webwork2.log.1
timing.log.1

You will not see a timing.log file unless someone has been doing something with WeBWorK. If there is no timing.log file do something yourself (e.g. login to a course) and then you should see

webwork2.log
webwork2.log.1
timing.log
timing.log.1

Now run logrotate again

sudo logrotate -f /etc/logrotate.d/webwork

and do something in WeBWorK and you should see

webwork2.log
webwork2.log.1
webwork2.log.2.gz
timing.log
timing.log.1
timing.log.2.gz

Here is what is going on. timing.log.1 was renamed to timing.log.2 and compressed giving timing.log.2.gz. timing.log was renamed to timing.log.1. A slightly different procedure occured for the webwork2.log file due to the copytruncate option. webwork2.log.1 was renamed to webwork2.log.2 and compressed giving webwork2.log.2.gz. That part is the same. However, webwork2.log was copied to webwork2.log.1, and webwork2.log was truncated. That means that the original webwork2.log file is still in place, but is now empty. This is important or the Mojolicious webwork2 app would lose its handle on the file and stop writing to it. A similar procedure will happen weekly until there are a total of 15 backups of each file after which the oldest one will be deleted.

Known Issues

Here are the known issues with this release.

PGbasicmacros.pl

Displaying certain symbols (e.g. {, },<,>,≤, ≥) in the text (not in Math Mode) of a WeBWorK problem fails. An example is Problem 1 in Set 0 in "myTestCourse" (see Test that Things are Working Properly below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. However the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.

If you do want to proceed with the fix we need to edit the PGbasicmacros.pl file.

$ cd /opt/webwork/pg/macros
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak
$ nano PGbasicmacros.pl

Look for the line

HTML_MathJax     => [ "HTML_dpng", "HTML_tth", "HTML", ],

and replace it by

#HTML_MathJax     => [ "HTML_dpng", "HTML_tth", "HTML", ],
HTML_MathJax     => [ "HTML_dpng", "HTML", "HTML_tth", ],

Then save the file and Quit.

Housekeeping

Remove temporary files

WebWorK no longer generates a lot of temporary files but it is still a good idea to clean them out once in awhile. Temporary files are stored under the directories /opt/webwork/webwork2/tmp and /opt/webwork/webwork2/htdocs/tmp. It is safe to delete everything in these tmp directories. If you want, you can follow the directions below to set up Cron jobs to do this automatically.

Using Cron Jobs to remove temporary files

It is a good idea to clean out temporary files on a regular automatic schedule. The following two cron jobs will accomplish this. They are run every six months (in January and July), on the first and second days of the month at 0330 hours. These cron jobs should be run as root. We use crontab to edit the crontab file:

$ sudo crontab -e

Now add the following lines at the end of the file

30 03 1 1,7 *  find /opt/webwork/webwork2/tmp/*  -name "*" ! -name "README" -delete
30 03 2 1,7 *  find /opt/webwork/webwork2/htdocs/tmp/* -name "*" ! -name "README" -delete

and save the file and quit.

Where to go From Here

You should play around with myTestCourse e.g. click on Library Browser and browse the Problem Library.

Look at A day in the life of a WeBWorK instructor.

Read Course Administration for more information about creating courses.

Under Categories below click on Administrators to see a listing of other WeBWorK documentation for system administrators.