# Installation Manual for 2.17 on Ubuntu

These instructions cover the installation of WeBWorK 2.17 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)). Note that the above images are currently for WeBWorK 2.16 on Ubuntu Server 20.04 LTS. Updated images will be available shortly.

## Notation

First some short comments on notation we will be using. We will use <key> to indicate that you should press a specific key (e.g. <Enter>, <Tab>, <F12>, etc.). Sometimes we will also use e.g. <wwadmin password> to indicate you have to enter the wwadmin password.

^ will indicate the <Ctrl> key so e.g. ^X is really shorthand for <Ctrl> <X>, i.e. press the Ctrl key and hit the X key.

Code blocks that begin with # must be run with root privileges (via either a root shell or prefixing the command with sudo). You can enter a root shell with sudo -s. Code blocks that begin with $ may be run as a standard user. You are not intended to type the # or $ characters as part of the provided commands.

## Installing 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. We suggest wwadmin but you can use whatever you want.

• 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, we will call this password the <wwadmin password>. 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.

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. ## Install 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 $ sudo apt-get update
$sudo apt-get 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. apache2 2. cpanminus 3. curl 4. dvipng 5. dvisvgm 6. gcc 7. git 8. imagemagick 9. libapache2-request-perl 10. libarchive-zip-perl 11. libarray-utils-perl 12. libcrypt-ssleay-perl 13. libdancer-perl 14. libdancer-plugin-database-perl 15. libdata-dump-perl 16. libdatetime-perl 17. libemail-address-xs-perl 18. libemail-sender-perl 19. libemail-stuffer-perl 20. libexception-class-perl 21. libextutils-xsbuilder-perl 22. libfile-find-rule-perl-perl 23. libgd-perl 24. libhtml-scrubber-perl 25. libhttp-async-perl 26. libiterator-perl 27. libiterator-util-perl 28. libjson-perl 29. liblocale-maketext-lexicon-perl 30. libmime-tools-perl 31. libmoox-options-perl 32. libnet-ip-perl 33. libnet-ldap-perl 34. libnet-oauth-perl 35. libossp-uuid-perl 36. libpadwalker-perl 37. libpath-class-perl 38. libphp-serialization-perl 39. libpod-wsdl-perl 40. libsoap-lite-perl 41. libsql-abstract-perl 42. libstring-shellquote-perl 43. libtemplate-perl 44. libtext-csv-perl 45. libtimedate-perl 46. libuuid-tiny-perl 47. libxml-parser-easytree-perl 48. libxml-parser-perl 49. libxml-writer-perl 50. libyaml-libyaml-perl 51. make 52. netpbm 53. npm 54. openssh-server 55. pdf2svg 56. preview-latex-style 57. texlive 58. texlive-latex-extra 59. 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 apache2 cpanminus curl dvipng dvisvgm gcc git imagemagick libapache2-request-perl \
libarchive-zip-perl libarray-utils-perl libcrypt-ssleay-perl libdancer-perl \
libemail-sender-perl libemail-stuffer-perl libexception-class-perl libextutils-xsbuilder-perl \
libfile-find-rule-perl-perl libgd-perl libhtml-scrubber-perl libhttp-async-perl \
libiterator-perl libiterator-util-perl libjson-perl liblocale-maketext-lexicon-perl \
libmime-tools-perl libmoox-options-perl libnet-ip-perl libnet-ldap-perl libnet-oauth-perl \
libpod-wsdl-perl libsoap-lite-perl libsql-abstract-perl libstring-shellquote-perl \
libtemplate-perl libtext-csv-perl libtimedate-perl libuuid-tiny-perl \
libxml-parser-easytree-perl libxml-parser-perl libxml-writer-perl libyaml-libyaml-perl \
make netpbm npm openssh-server pdf2svg preview-latex-style texlive texlive-latex-extra unzip


Enter the password for wwadmin at the prompt:

[sudo] password for wwadmin: <wwadmin password>


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. For example, one module, Statistics::R::IO that will be needed is not in a standard package. We also need SQL::Abstract::Classic. To install these

$sudo cpanm Statistics::R::IO SQL::Abstract::Classic [sudo] password for wwadmin: <wwadmin password>  Below, we will determine other perl modules that will need to be installed with this method. ## Setting up 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. ### enabling info.conf and status.conf in Ubuntu We enable the info module. Acting as root in a terminal window enter $ sudo a2enmod info


Next we make a copy of the configuration files we will be editing for safekeeping.

$cd /etc/apache2/mods-available  $ sudo cp info.conf info.conf.bak1
$sudo cp status.conf status.conf.bak1  Now we will edit configuration files info.conf and status.conf 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 nano. Note that you have to be root to edit these files. First we edit info.conf $ cd /etc/apache2/mods-available
$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 # from)  Require ip 192.0.2.0/24  and then replace Require ip 192.0.2.0/24 by Require host math.yourschool.edu (or Require host yourschool.edu if you want to allow wider access) where of course you should edit math.yourschool.edu appropriately. You could also use a specific or range of ip addresses following the syntax in the example. Then save the file and quit (press ^X, Y, <Enter>). Now we edit status.conf $ cd /etc/apache2/mods-available
$sudo nano status.conf  Edit the  #Require ip 192.0.2.0/24  line just as you did for info.conf. Then save the file and quit. And restart Apache so that the above changes take effect $ sudo systemctl restart apache2


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

Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) may not start.

### Test Apache

Now restart Apache

$sudo systemctl restart apache2 password:<wwadmin password>  or $ sudo apache2ctl restart


or

$sudo service apache2 restart [sudo] password for wwadmin: <wwadmin password>  and test your server by connecting to your server ("http://yourserver.yourschool.edu") from a browser on a remote machine. You should see the Apache2 Ubuntu Default Page indicating that Apache is running. You can check Apache's status by connecting to "http://yourserver.yourschool.edu/server-status" from a browser on a remote machine in the math.yourschool.edu domain. Further test Apache by connecting to "http://yourserver.yourschool.edu/server-info" 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 Server Settings you should see 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 mod_apreq2 and mod_perl 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 /var/log/apache2/error.log. In the directory /var/log/apache2/ you can "less" through the error log (less error.log), look at the last few entries (tail error.log) or run the command tail -f error.log 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 ^C to break out of tail -f . 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 mod_apreq2 and mod_perl are installed and running.

## Installing 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 MariaDB using the distro and cpan packages.

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


### Securing the Database

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

$sudo mysql_secure_installation [sudo] password for wwadmin: <wwadmin password>  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 ...


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.

MariaDB> exit
Bye
$ ## Downloading the WeBWorK System Software and Problem Libraries We are finally at the point where we can start downloading and installing WeBWorK. 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 the following are rather 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
$mkdir downloads$ cd downloads
$git clone https://github.com/openwebwork/webwork2.git$ git clone https://github.com/openwebwork/pg.git
$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.17 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 ## 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.16_to_2.17. ### Move the System into the Required Directories As root create a webwork directory under /opt, change the ownership of the webwork directory to www-data, which is what the apache server runs as and move directories there. $ cd
$cd downloads$ sudo mkdir /opt/webwork
$sudo chown www-data:www-data /opt/webwork$ sudo mv webwork2 /opt/webwork/
$sudo mv pg /opt/webwork/  Now create the courses and libraries directories under webwork and copy and move content there $ sudo mkdir /opt/webwork/courses
$sudo mkdir /opt/webwork/libraries$ sudo mv webwork-open-problem-library /opt/webwork/libraries/
$cd /opt/webwork/webwork2/courses.dist$ sudo cp *.lst /opt/webwork/courses/
$sudo rsync -a modelCourse /opt/webwork/courses/  ### Setting Permissions The PG installation directory and files should be owned by www-data and not writable by other users: $ cd /opt/webwork/pg
$sudo chmod -R u+rwX,go+rX .  Most WeBWorK directories and files should also be owned by www-data and not writable by other users: $ cd /opt/webwork/webwork2
$sudo chmod -R u+rwX,go+rX .  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 webservices 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 runing

$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. $ sudo -s
# cd /opt/webwork/webwork2/
# chgrp -R www-data DATA ../courses htdocs/tmp logs tmp /opt/webwork/pg/lib/chromatic
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp /opt/webwork/pg/lib/chromatic
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a -exec chmod g+s {} \;
# exit
$gcc color.c -o color  You may see some warning messages which you can safely ignore. ## Configuring 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.bak1  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  ## Install node and npm WW 2.17 requires newer versions of node and npm than are in the Ubuntu repositories. This is a bit complicated because of issues with an older installed version (see e.g. https://github.com/nodesource/distributions/issues/1157). Run the commands: $ cd /etc/apt/sources.list.d
$sudo rm nodesource.list  Update apt, fix the install, remove nodejs and the nodejs-doc packages $ sudo apt --fix-broken install
$sudo apt update$ sudo apt remove nodejs
$sudo apt remove nodejs-doc$ sudo apt autoremove


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


## Checking Module Dependencies

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 apache2  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. ### Obtaining Javascript Libraries Javascript libraries are now 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 install$ cd /opt/webwork/pg/htdocs/
$npm install  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: $ cd /opt/webwork/webwork2/htdocs/
$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

There is a bug in the Perl XMLRPC::Lite package that occurs with UTF8 characters. This can be fixed by applying the following patch:

$sudo patch -p1 -d / < /opt/webwork/webwork2/docker-config/xmlrpc-lite-utf8-fix.patch  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


## Configuring WeBWorK

### Making 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 the Apache2 server setup. 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. #### 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 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. 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 is 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. #### 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. ### 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> notice that you have to replace database_password with the password you set when editing site.conf above): $ sudo mysql

MariaDB > CREATE DATABASE webwork;
MariaDB > GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO 'webworkWrite'@'localhost';
Bye
$ where as we said replace database_password with the password you set when editing site.conf above. ### Configuring Apache WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named webwork.apache2.4-config.dist and located in the conf directory. First, copy the file to webwork.apache2-config: $ cd /opt/webwork/webwork2/conf
$cp webwork.apache2.4-config.dist webwork.apache2.4-config  and now link it into your Apache configuration process $ sudo ln -s /opt/webwork/webwork2/conf/webwork.apache2.4-config /etc/apache2/conf-enabled/webwork.conf


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.

$sudo a2dismod mpm_event$ sudo a2enmod mpm_prefork


WeBWorK requires the Apache 2 rewrite module to be enabled for serving files in the pg/htdocs location.

$sudo a2enmod rewrite  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. $ 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


$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_prefork.conf $ cd /etc/apache2/mods-available/
$sudo nano mpm_prefork.conf  Search for the lines  MaxRequestWorkers 150 MaxConnectionsPerChild 0  Which occur under <IfModule mpm_prefork_module> 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 MaxRequestWorkers 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. Finally we copy WeBWorK's icon file favicon.ico to Apache's html directory. $ sudo cp /opt/webwork/webwork2/htdocs/favicon.ico /var/www/html


Now stop and start Apache. We do it this way to make sure the MPM gets changed.

$sudo systemctl stop apache2 [sudo] password for wwadmin: <wwadmin password>$ sudo systemctl start apache2


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 (e.g. one time a wrapped line in localOverrides.conf caused me problems, another time it was a missing single quote). 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. Another thing is to look at the Apache error log which is located at /var/log/apache2/error.log.

$cd /etc/apache2/$ diff apache2.conf apache2.conf.bak1
$cd /opt/webwork/webwork2/conf/$ diff site.conf site.conf.dist
$diff localOverrides.conf localOverrides.conf.dist$ diff webwork.apache2.4-config webwork.apache2.4-config.dist
$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 $ sudo systemctl restart apache2


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 --db-layout=sql_single --users=adminClasslist.lst --professors=admin


### Updating 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:

$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.16 Virtual Machine Image and in the WW 2.16 Amazon Machine Image is current as of August 1, 2021. 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. ## Starting and Stopping Apache and MySQL If you make changes to the system, you will have to restart apache2 before the changes take effect. On rare occasions you may need to restart MySQL. ### Starting and Stopping Apache You have to run these commands as root. To start or restart (i.e. stop and then start) the apache2 webserver run the command $ sudo apache2ctl graceful


You can also start apache2 by

$sudo apache2ctl start [sudo] password for wwadmin: <wwadmin password>  and restart it with $ sudo apache2ctl restart


restart is less graceful but more powerful than graceful. Sometimes graceful fails to kill all apache2 child processes.

To stop the Apache webserver run the command

$sudo apache2ctl stop [sudo] password for wwadmin: <wwadmin password>  Stopping and then starting Apache should definitely kill all apache2 child processes. You can also start or stop apache2 by using the apache2 service. Run $ sudo service apache2


and you will get a list of allowed commands (start, stop, restart, etc.).

Finally you can use the newer systemctl method, e.g.

sudo systemctl start apache2

sudo systemctl --help


will give you a list of all possible commands, the main ones being start, stop, restart and status.

Note that systemctl is the preferred method on modern versions of Ubuntu.

### Starting and Stopping MySQL or MariaDB

You have to run these commands as root.

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


To get a list of all possible commands run

$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 the 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 controled by the editors). This step creates a button in the Library Browser which gives a direct link to the Contrib directory. Put a link to the Contrib directory in the /opt/webwork/courses/modelCourse/templates/  directory so that when we create courses copying templates from the modelCourse, the Contrib directory will be available. Actually this link, called Contrib, has already been added 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 in the modelCourse above, and then do the following. Note we don't have any individual courses yet. But for example after creating myTestCourse below, to set up access to the Contrib directory from myTestCourse, do the following $ cd /opt/webwork/courses/myTestCourse/templates/
$sudo$ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib Contrib


### 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/$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Union unionLibrary
$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. 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 either of these files you must restart the Apache webserver in order for these changes to take effect.

Since we have edited global.conf and haven't restarted Apache we do so now.

$sudo apache2ctl graceful password:<wwadmin password>  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 Course 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 and Copy simple configuration file to new course checked 6. Add an additional instructor if you wish 7. Copy templates from: modelCourse (the default action) 8. Click on Add Course 9. 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 Apache error log which is located at /var/log/apache2/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 Take Action! Now click on Homework Sets on the Main Menu and click on Demo. Then look at the problems. Mathematical equations should be typeset. If not, edit the file Constants.pm in the directory /opt/webwork/webwork2/lib/WeBWorK. Change the line $WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0; to ...::PreserveTempFiles = 1;. Then restart Apache and view the first couple problems or some new ones. Then look in the directory /opt/webwork/webwork2/tmp/. cd to one of the ImageGenerator.../tmp/ directories and look at the error and log files there. When you fix the problem remember to edit ...::PreserveTempFiles = 1; 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.

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

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 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 Generate hardcopy for selected users and selected sets. If you get an error (you shouldn't) just click Download Hardcopy 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 $WeBWorK::ContentGenerator::Hardcopy::PreserveTempFiles to 1 in the file Constants.pm in the directory /opt/webwork/webwork2/lib/WeBWorK and then restart Apache. Remember to set this back to 0 after debugging. 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 you will see an error from setmaker.js: /webwork2/instructorXMLHandler: e.g. Timeout or Forbidden), 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.

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.

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://192.168.76.128/webwork2/admin
http://192.168.76.128/webwork2/mytestcourse


where of course you should use your actual ip address or url.

### Replace the default landing page

You probably should replace /var/www/html/index.html with a page which redirects to the webwork course list at your site. Something like the following should work:

 <html>
<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>
<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>


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

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 creates a separate directory on which are stored all of WeBWorK's "temporary" files. These are mostly small files such as png images of equations, pdf files, etc. that may be reused but if they are not present (e.g. if they get deleted) they will be seamlessly regenerated on the fly. It is very convenient to set up a separate directory for these temporary files and we recommend that you do so.

Option B installs and configures a lightweight webserver. Apache is a very standard and powerful webserver which we use to serve WeBWorK pages. However its child processes use a lot of resources (e.g. memory). When serving static files and images and running MathJax, a much lighter weight webserver can be used. This can substantially reduce the load on a heavily used server.

Option C configures Apache (and optionally lighttpd if installed) so that access to WeBWorK will be through an encrypted connection (SSL) with an https: URL.

Option D 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 E sets up log rotation for WeBWorK's timing log.

### Implement Option A (wwtmp)

Now is the time to implement Option A if you choose to do so. Actually you can do this at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that temporary files will be stored in a different location. First have to create the directory /var/www/html/wwtmp with the command

sudo mkdir /var/www/html/wwtmp


All of WeBWorK's "temporary" files will be stored under /var/www/html/wwtmp. These are mostly small files such as png images, pdf files, etc. that may be reused but if they are not present (e.g. if they get deleted) they will be seamlessly regenerated on the fly. There is no reason to back up such files and having them in a separate directory means that it is easier and faster to run back ups and skip backing up unnecessary files.

First we set the group and permissions for the wwtmp directory

$sudo -s [sudo] password for wwadmin: <wwadmin password> # cd /var/www/html # chown wwadmin wwtmp # chgrp www-data wwtmp # chmod ug+w wwtmp # chmod g+s wwtmp # exit$


Next we have to edit localOverrides.conf so that WeBWorK uses the new wwtmp directory. Since we have a working WeBWorK system, first we make a backup copy of localOverrides.conf.

$cd /opt/webwork/webwork2/conf$ cp localOverrides.conf localOverrides.conf.bak1
$nano localOverrides.conf  Now edit localOverrides.conf. Search for the line # Directory for temporary files  and under that find the line # To implement, uncomment the following 6 lines:  Then uncomment (i.e. remove the # symbol) from the 6 lines #$webworkDirs{htdocs_temp}  =  '/var/www/html/wwtmp';
#$webworkURLs{htdocs_temp} = '/wwtmp'; #$webworkDirs{equationCache} = "$webworkDirs{htdocs_temp}/equations"; #$webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations"; #$courseDirs{html_temp}  =  "/var/www/html/wwtmp/$courseName"; #$courseURLs{html_temp}   = "/wwtmp/$courseName";  IMPORTANT NOTE. Apache 2.4 has changed the default location of the document root from /var/www to /var/www/html and we are in the process of updating the file localOverrides.conf.dist to reflect this. If your copy of this file does not have /html in the two lines above, then in addition to uncommenting the 6 lines you also have to add /html in two places. Then save the file and quit. If you look at the wwtmp directory you will find it empty but after you restart apache and then access some WeBWorK problems, you will find temporary directories and files in wwtmp. Remember your have to restart apache for these changes to take effect. #### Using Cron Jobs to remove temporary files It is a good idea to clean out temporary files on a regular automatic schedule. Also pdf copies of downloaded problem sets are saved in a temporary directory (wwtmp/.../hardcopy) so that they can be downloaded from the web. But after the download, the pdf file remains and is visible from the web if one knows the URL. For this reason we recommend deleting all such files that are over one hour old. Similarly we recommend deleting all png, gif, and html links under wwtmp that are over 30 days old. And finally every week we recommend deleting all equation images that are over 14 days old. The following cron jobs will accomplish this. The first is run every 30 minutes, the next three twice a month and the last one weekly on Sunday morning. These cron jobs should be run as root. We use crontab to edit the crontab file: $ sudo -s
# crontab -e


Now add the following lines at the end of the file

WEBWORK_ROOT=/opt/webwork/webwork2
*/30 * * * *  find /var/www/html/wwtmp/*/hardcopy/*  -mmin +60  -name "*" -delete
5 5 1,15 * *  find /var/www/html/wwtmp/*/gif/  -mtime +30  -name "*" -delete
5 5 2,16 * *  find /var/www/html/wwtmp/*/png/  -mtime +30  -name "*" -delete
5 5 3,17 * *  find /var/www/html/wwtmp/*/html/  -mtime +30  -name "*" -delete
4 5 * * 0 /opt/webwork/webwork2/bin/remove_stale_images --delete --days 14


and save the file and quit

# exit
$ ### Implement Option B (lighttpd) As is the case for Option A you can implement Option B at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that static images, pages and MathJax (if you installed it locally) will be served by a light weight web server. #### Install and Configure lighttpd First we install the light weight webserver lighttpd Run the command $ sudo apt install lighttpd


Now we configure lighttpd. First let's make a backup of the configuration file.

$cd /etc/lighttpd$ sudo cp lighttpd.conf lighttpd.conf.bak1


Now edit lighttpd.conf.

$sudo nano lighttpd.conf  Apache2 is listening on port 80 so we need an alternate port for lighttp to listen to. Standard alternate ports for this are usually 81, 8000, or 8080. 8080 is the only port that is listed as an official alternate at http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers . Note that in rare cases an institution may block httpd requests to port 8080. If any of your students report that they can not see graphics, they will have to request that access to requests to port 8080 be allowed. Find the line server.port = 80  and replace it by server.port = 8080  Now we make a few more changed that allow MathJax to run under lighttpd. You can skip these if you are running MathJax remotely. At the top of the file in the section  server.modules = , under the line  "mod_redirect",  add the line "mod_setenv",  Then below the closing parentheses and above the line server.document-root = "/var/www/html"  add the lines setenv.add-response-header = ( "Access-Control-Allow-Origin" => "*" ) alias.url = ( "/webwork2_files" => "/opt/webwork/webwork2/htdocs/" )  Then save the file and quit. Now restart lighttp $ sudo systemctl restart lighttpd


#### Test lighttpd

First run the command

 $sudo lsof -i -P -n | grep LISTEN  and check that lighttpd is listening on port 8080 Now test your server by connecting to your server from a browser on a remote machine ("http://yourserver.yourschool.edu:8080/"). You should see the Apache2 Ubuntu Default Page but without a graphic for the Ubuntu Logo indicating that lighttp is running . Test the /webwork2_files location by visiting "http://yourserver.yourschool.edu:8080/webwork2_files. You should see the "WeBWorK Placeholder Page". #### Configure WeBWorK to Take Advantage of Lighttp First let's make a backup copy of localOverrides.conf  so that we can easily back out of these changes if necessary. $ cd /opt/webwork/webwork2/conf
$cp localOverrides.conf localOverrides.conf.bak2  Now edit localOverrides.conf. Note that while Option B is independent of Option A, we assume most people implementing Option B will have already implemented Option A. Therefore we give instructions for editing localOverrides.conf assuming that Option A has been implemented. If this is not the case, modify the instructions below accordingly. Also replace yourserver.yourschool.edu with the correct address. $ nano localOverrides.conf


Find the line

$webworkURLs{htdocs_temp} = '/wwtmp'  and replace it by #$webworkURLs{htdocs_temp}   = '/wwtmp';
$webworkURLs{htdocs_temp} = 'http://yourserver.yourschool.edu:8080/wwtmp';  Find the line $courseURLs{html_temp}   = "/wwtmp/$courseName";  and replace it by #$courseURLs{html_temp}   = "/wwtmp/$courseName";$courseURLs{html_temp}   = "http://yourserver.yourschool.edu:8080/wwtmp/$courseName";  If you installed MathJax locally under the above line add the lines # Location of MathJax script, used for the MathJax display mode.$webworkURLs{MathJax}       = 'http://yourserver.yourschool.edu:8080/webwork2_files/mathjax/es5/tex-chtml.js';


If you are running MathJax remotely, don't add the above lines.

Then save the file and quit.

Now restart apache and lighttp.

$sudo apache2ctl graceful password:<wwadmin password>$ sudo systemctl restart lighttpd


#### Test that Everything is Working Properly

To test things go to your test course http://yourserver.yourschool.edu/webwork2/myTestCourse/. Log into your course and view a problem with a graphic image (e.g. Problem 2 of the Demo set. Since you have Admin or Prof privileges, you can view sets which are not yet open). Right click on the image and click on Properties (or whatever is appropriate on your browser, e.g. copy image location) and check that the image is being served from port 8080 (something like http://yourserver.yourschool.edu:8080/wwtmp/myTestCourse/images/...).

If MathJax is installed locally, to test that MathJax is using lighttpd, view a problem with some typeset equations. Right click on the equation and you should see the MathJax menu which confirms MathJax is being used. Next look at the source code for the page (e.g. right click on most browsers and select "View page source") and in the source, search for tex-chtml.js. You should see that this is being loaded from port 8080. Obviously, if you are running MathJax remotely, you will see it is being loaded from the CDN.

#### Disabling Option B (lighttpd) for a single course

If your server is hosting courses from different institutions, you may find that you need to disable using lighttpd for a single course, e.g. because the institution blocks access to port 8080. Actually since port 8080 is an "official" alternate httpd port, you should first try to get the network administrators at the institution to grant access to port 8080. Failing this, you can disable using lighttpd and instead use apache for a single course by adding the following lines to the end of the course's course.conf file which is located in the top level directory for the course (usually /opt/webwork/courses/course_name). Note that using apache instead of lighttpd will put a slightly larger load on the server. Also note that you need "admin" level privileges to edit the course.conf file. Instructors with only "professor" level privileges can not do this from within WeBWorK. If you are running MathJax remotely, don't add the last line.

# Do not use lightppd (port 8080) for this course
$webworkURLs{htdocs_temp} = '/wwtmp';$courseURLs{html_temp}   = "/wwtmp/$courseName";$webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations";$webworkURLs{MathJax}       = "$webworkURLs{htdocs}/mathjax/es5/tex-chtml.js";  I repeat if you are running MathJax remotely, don't add the last line above. ### Implement Option C (SSL) Option C 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. If you have implemented Optiona B, the non encrypted lighttpd server will be used for images, MathJax, etc. so we might have to set up the lighttpd server to run under SSL (see below). 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 When we installed the package openssh-server a self-signed certificate was automatically created. The certificate is stored at /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 make-ssl-cert generate-default-snakeoil --force-overwrite


which you might want to do since I believe the original certificate is only valid for 365 days.

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

First we enable the mod_ssl module

$sudo a2enmod ssl [sudo] password for wwadmin: <wwadmin password>  Now we have to configure Apache to use SSL. $ cd /etc/apache2/sites-available/
$sudo cp default-ssl.conf default-ssl.conf.bak1 [sudo] password for wwadmin: <wwadmin password>$ sudo nano default-ssl.conf


Our self-signed certificate and key files are named ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key. 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-20-04

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 [sudo] password for wwadmin: <wwadmin password>  Finally we restart Apache $ sudo systemctl restart apache2


and test things. Connect to https://yourserver.yourschool.edu/webwork2/myTestCourse You will be asked to accept the certificate. After you do so things should work just as before except that the connection will be via https except for images, MathJax, etc. if you using lighttp. In that case, viewing math expressions in image mode should work fine but it is possible using MathJax mode will fail. We will talk about this below.

#### 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.bak1
$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 service apache2 restart


and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.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 apache

sudo service apache2 restart


#### Configure lighttpd to use SSL

We are using lighttpd for images, pdf's and MathJax (if MathJax is installed locally) MathJax may fail (so mathematical expressions will not be displayed) if it runs under lighttpd and you do not configure lighttpd to use SSL. So let's configure lighttpd to use SSL.

For lighttpd you need to concatenate the key file and the certificate file into a single pem file by running the following command. Obviously you should use the real name of your certificate and key files, not "apache.key" and "apache.crt".

$sudo -s [sudo] password for wwadmin: <wwadmin password> # cd /etc/ssl/private # cat apache.key ../certs/apache.crt > apache.pem # chmod 640 apache.pem # exit$


If you are using official certificates, 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. See e.g. http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_SSL and/ or https://www.vultr.com/docs/setup-let-s-encrypt-with-lighttpd-on-ubuntu-16-04

Since we already are using the files ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key for apache, we will also use them for lighttpd

$sudo -s [sudo] password for wwadmin: <wwadmin password> # cat /etc/ssl/private/ssl-cert-snakeoil.key /etc/ssl/certs/ssl-cert-snakeoil.pem >/etc/lighttpd/lighttpd.pem # exit$


Now edit lighttpd.conf.

$cd /etc/lighttpd$ sudo cp lighttpd.conf lighttpd.conf.bak2
$sudo nano lighttpd.conf  First in the list of server.modules at the top of the file, under the last module "mod_setenv",, add the module "mod_openssl",  Next under the line server.port = 8080  add the following $SERVER["socket"] == ":8443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/lighttpd.pem"
}


Then save the file and quit.

And restart lighttpd and check it's status

$sudo systemctl restart lighttpd [sudo] password for wwadmin: <wwadmin password>$ sudo systemctl status lighttpd


Sometimes when Lighttpd would not restart (or start) I just rebooted the server and everything worked. If you have difficulty you can run the command

$sudo lsof -i -P -n | grep LISTEN  which will list all the ports your server is listening to. In the list you should see something similar to lighttpd 519 www-data 5u IPv4 18610 0t0 TCP *:8443 (LISTEN)  ##### Edit localOverrides.conf $ cd /opt/webwork/webwork2/conf
$cp localOverrides.conf localOverrides.conf.bak4$ nano localOverrides.conf


and replace all occurrences of 8080 by 8443 (one occurrence in three different lines). Then in these same three lines replace http by https . Obviously, you have to edit the three active lines and can ignore the commented out lines.

Then save the file and quit. And restart apache

$sudo service apache2 restart [sudo] password for wwadmin: <wwadmin password>  and test that all is well by viewing a page with math expressions using MathJax mode. ### Implement Option D (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 3.6.3 (2020-02-29) -- "Holding the Windsock" Copyright (C) 2020 The R Foundation for Statistical Computing ... Type 'q()' to quit R. >  and then quit > q() Save workspace image? [y/n/c]: n  #### Update Rserve The version of Rserve installed above has a bug (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=6376#p17335) so we need to install a newer version. Do the following $ sudo R
...
>


and run the command

> install.packages("Rserve",lib="/usr/lib/R/site-library","http://rforge.net")


and then quit R

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


#### Configure Webwork with the location of the R server

Edit the localOverrides.conf file

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



Search for the line

#$pg{specialPGEnvironmentVars}{entryAssist} = 'WIRIS';  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


Finally we enable the service to start when the system starts

$sudo systemctl enable rserve.service  #### 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. 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)]);


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 E (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 timing.log gives timing information on every action in WeBWorK (see WeBWorK_performance) and can be used to assess the performance of your server. #### 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
}


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

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

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

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. And the something you (or someone else) did in WeBWorK created a new timing.log 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

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.

To fix this we need to edit the PGbasicmacros.pl file.

$cd /opt/webwork/pg/macros$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1

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

However this 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 probably 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 above fix.

## Housekeeping

### Remove snapd

snapd which is installed by default on Ubuntu can use a lot of resources. If you want to remove it, see e.g. https://www.simplified.guide/ubuntu/remove-snapd

## Where to go From Here

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