Installing from WW2.15 Ubuntu20.04 Server Virtual Machine Image

This article is under construction. Use the information herein with caution until this message is removed.

These instructions cover the installation of the Ubuntu Server 20.04 LTS 64 bit operating system and WeBWorK 2.15 using the WeBWorK Virtual Machine Image.

The WeBWorK Virtual Machine Image is an .ova file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, AWS, Google Cloud, etc. This image file has been tested on VMware Workstation 15 Player, .

This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Apache2, MySQL, R server, lighttpd, log rotation, etc.) installed and configured.

Installing from WW2.15 Ubuntu20.04 Server Virtual Machine Image

Overview

After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 20.04 LTS system with WeBWorK, Apache2, MySQL, R server, lighttpd, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user wwadmin (who has sudo privileges), for the MySQL user webworkWrite who has access to MySQL, for the WeBWorK user admin who has admin privileges and for the WeBWorK user profa who has professor privileges (see below). Finally you will have to install OpenSSH (since this has to be done locally) to gain SSL access to your server and you should set up SSL (https) access to WeBWorK if students will be using your server.

There are more detailed instructions for Ubuntu Server 20.04 and WeBWorK 2.15 at Installation_Manual_for_2.15_on_Ubuntu_20.04_Server.

Download the ova image

There is only a 64 bit distribution. The 64 bit distribution should work with most modern cpu's. Download the sha1 checksum and the .ova file from the site below. The ova is a 4.3 GB file.

MAA

Verify the SHA1 checksum of your downloaded file WW2.15_Ubuntu20.04_Server.ova agrees with the one in WW2.15_Ubuntu20.04_Server.ova.sha1.

OVA and OVF Files

The .ova file is simply a tar bundle containing an .ovf file, one or more .vmdk files and a .mf file.

The .ovf file is an XML file which describes the packaged virtual machine and is human-readable.
The .vmdk file(s) contain the disk images(s).
The .mf file contains SHA1 checksums for the above files.

You can import a virtual machine either from an .ova file or from the .ovf, .vmdk, .mf collection. Sometimes importing from the .ova file may fail whereas importing from the .vmdk file will succeed.

You can extract the files in WW2.15_Ubuntu20.04_Server.ova with the command

$  tar -xvf WW2.15_Ubuntu20.04_Server.ova

You then can look at (and possibly edit) the human readable WW2.15_Ubuntu20.04_Server.ofv file. If you do edit the WW2.15_Ubuntu20.04_Server.ofv file, you will also have to compute the new SHA1 checksum and replace the old one in the WW2.15_Ubuntu20.04_Server.mf file for the files to be usable.

Installing the WeBWorK Virtual Machine Image

Import the file WW2.15_Ubuntu20.04_Server.ova into your virtualization software package (e.g. VMware, VirtualBox). The ova file was created on VMware Workstation 15 Player running on a Windows 10 host. It has been tested on

VMware Workstation 15 Player running on a Windows 10 host

See Specific Virtual Environments below for installation information on specific virtual environments.

Processors, Memory, Hard Disk

The WeBWorK Virtual Machine Image was created with the following parameters:

12 GB dynamically allocated hard drive in VMDK format (single file)
1 GB memory
1 cpu

The above resources are very minimal and (except for maybe disk space) correspond to a AWS t2-micro level machine which is free.

Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they will for VMware Workstation 15 Player running on a Windows 10 host). You should be adjust these resources either when when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk may be more complicated (consult the documentation for your virtual machine environment). After you have expanded the hard disk, you will still have to make the extra space available to Ubuntu (see [[ ]] below).

Import the .ova File

There may be specific information for your situation below. See

VMware Workstation 15 Player running on a Windows 10 host
VMware Workstation 15 Pro
VirtualBox 6

Your Server

After importing, your virtual WeBWorK server will be identical to a system created by following the instructions Installation_Manual_for_2.15_on_Ubuntu_20.04_Server with all Optional Configurations A-E implemented except that

openssh-server is not installed
Optional C (SSL) is not implemented
The PGbasicmacros.pl file has been slightly changed (see PGbasicmacros.pl below)

Both the installation of openssh-server and the implementation of Optional C (SSL) and must be done locally (see below)

Note that on some virtual environments, you may need to take additional actions. See the section Specific Virtual Environments below.

You should read through the instructions Installation_Manual_for_2.15_on_Ubuntu_20.04_Server to understand how your server has been set up. Especially look at Installation_Manual_for_2.15_on_Ubuntu_20.04_Server#Terminal Window Notation and Use to understand the notation we use in these instructions.

PGbasicmacros.pl

The PGbasicmacros.pl file (in the directory /opt/webwork/pg/macros) has been slightly changed to fix a small bug. The original file is PGbasicmacros.pl.bak1 in the same directory. This may or may not be addressed in a WeBWorK 15 hotfix.

Boot your server

Log into your server

You should see a login prompt (you may have to press <Enter>).

Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges.

If your network uses DHCP, networking will be automatically configured for your system.

Install openssh-server

We need to install the openssh-server so that you can ssh into your server from your host or remote locations. In the directions below, the <wwadmin password> is "wwadmin" until you change it.

$ sudo apt install openssh-server
[sudo] password for wwadmin: <wwadmin password>

Now you can connect remotely to your server with ssh but you may have to reboot your server for this to take effect.

Accessing Your Server from a Terminal Emulator on your Host

At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program.

You can do all of the remaining installation from a terminal emulator on your host. 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).

My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and you new server's ip address (not domain name). After that if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.

I am assuming your network has been set up automatically.

The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command

$ ip address show

and looking at the output, 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

(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 .

If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a terminal emulator running on your host using ssh, or from the terminal on the guest once you login.

Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.

VMware Workstation 15 Player running on a Windows 10 host
VMware Workstation 15 Pro
VirtualBox 6

Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.

Set the Timezone for your server

To find out what timezone your server is set to run the command

$ timedatectl

and you will probably see

...
Time zone: America/New_York (EDT, -0400)
...

which may not be where you live. The timezone naming convention uses a “Region/City” format and to find the correct one for your location run the command

$  timedatectl list-timezones

Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.

$ sudo timedatectl set-timezone America/Los_Angeles
[sudo] password for wwadmin: <wwadmin password>

and then

$ timedatectl

to check it was set correctly.

Checking for and installing hotfixes

Follow the instructions at Installation_Manual_for_2.15_on_Ubuntu_20.04_Server#Checking for and Installing Hotfixes

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 backup and edit site.conf

$ cd /opt/webwork/webwork2/conf
$ cp site.conf site.conf.bak1
$ nano site.conf

First we have to edit information about the Apache2 server setup. Search for 192.168.204.128 and replace that by your the new ip address you found above (192.168.76.128 in our example above). The edited line should look like

$server_root_url   = 'http://192.168.76.128';

where of course your ip address may be different. The "http://" is important.

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.

Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then. 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.

Then save the file and Quit.

The defaults.config file

If you want WeBWorK questionnaires or similar things from different courses to be mailed to a central person or persons (e.g. the WeBWorK administrator), in defaults.config, you will see the lines

$mail{allowedRecipients}     = [
   #'prof1@yourserver.yourdomain.edu',
   #'prof2@yourserver.yourdomain.edu',
];

But we are not supposed to edit the defaults.config file, so if we want to do this, we will copy this to localOverrides.conf and edit it appropriately. Note that we should move this setting to the site.conf file.

Edit the localOverrides.conf file

Now backup and edit localOverrides.conf

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

First we have to replace all occurrences of 192.168.204.128 by your the new ip address you found above (192.168.76.128 in our example above). You can do this one by one or by a global search and replace:

^ \
Search (to replace) [...]:192.168.204.128
Replace with:192.168.76.128
A

where of course replace 192.168.76.128 by your actual ip address

As we said above, if you want WeBWorK questionnaires or similar things from different courses to be mailed to a central person or persons (e.g. the WeBWorK administrator), in localoverrides.config, add and then edit the lines

$mail{allowedRecipients}     = [
   #'prof1@yourserver.yourdomain.edu',
   #'prof2@yourserver.yourdomain.edu',
];

Then save the file and Quit.

Now restart apache so that our changed to the conf files takes effect.

$ sudo apache2ctl restart
[sudo] password for wwadmin: <wwadmin password>

Once access to your WeBWorK server is set up (as it should be now), if all you want to do is test out WeBWorK yourself without any other users, you are all set at this point but please read the rest of these instructions so that you understand how insecure your WeBWorK server is right now.

Test that Things are Working Properly

Connect to http://192.168.76.128/webwork2 where of course you should use your actual ip address. 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.

You should see the WeBWorK Welcome page with "Course Administration" and "myTestCourse" listed. At some point you may want to "hide" them so that they are not listed on the Welcome page (more on the later).

Click on "myTestCourse" and login with login name "profa" and password "profa". At this point you are a regular professor. There is also an administrator "admin", a regular student "jsmith" and several guest or practice users (who don't require a password but can view problems and "check" answers without them being "submitted" for credit). More on these below.

Now click on Homework Sets on the Main Menu and click on Demo. Then look at the problems. Mathematical equations should be typeset.

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

Another thing to do is to use Email on the Main Menu assuming you have set email up. 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).

Passwords

It is IMPERATIVE that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access. Also it is IMPERATIVE that you CHANGE THE PASSWORD for the MySQL user webworkWrite who has login privileges to MySQL. Otherwise anyone can connect to MySQL server and pretty easily gain access to the WeBWorK database. Finally it is IMPERATIVE that you CHANGE THE PASSWORD for the WeBWorK user admin who has admin privileges both in the admin course and in the myTestCourse and for the WeBWorK user profa who has professor privileges in the myTestCourse. Otherwise anyone can connect to WeBWorK server and pretty easily gain access and do anything they want.

Change the password for wwadmin

$ passwd
Changing passwd for wwadmin:
(current) UNIX password: wwadmin
Enter new UNIX password: <new wwadmin password> 
Retype new UNIX password: <new wwadmin password>
passwd: password update successfully
$

Do not forget the <new wwadmin password> that you just entered.

Change the password for webworkWrite

Now we change the passwords for the MySQL user webworkWrite. First we edit site.conf.

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

Search for $database_password = "wwadmin"; and replace this by
$database_password = "database_password"; where of course you should replace 'database_password' with your own password. We refer to this password as <database_password>. Remember it as we will need it shortly. Then save the file and Quit.

Then restart Apache so the changes take effect.

$ sudo apache2ctl graceful
[sudo] password for wwadmin: <wwadmin password>
$

and start MySQL

$ sudo mysql
[sudo] password for wwadmin: <wwadmin password>

You should see

Welcome to the MySQL monitor ...
mysql>

Now lets check the MySQL users.

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

You will see a table with six users (debian-sys-maint, mysql.infoschema, mysql.session, mysql.sys, root and webworkWrite). You should see that five users have a valid password (which will be displayed in encrypted form) and root is authenticated by a socket.

Now we will change the password for the webworkWrite User

mysql> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';

where of course you should replace <database_password> by whatever you used above (use the single quotes but no angle braces). Then

mysql> FLUSH PRIVILEGES;
use your up arrow key to run the command
mysql> SELECT Host, User, authentication_string FROM mysql.user;

and you should see that webworkWrite has a new passwords (which will be displayed in encrypted form).

Then exit MySQL

mysql> exit
Bye
$

If you want to check that you set the password correctly, do the following:

mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp
Enter password: <database_password>

and you should see

Welcome to the MySQL monitor ...
mysql>

Now exit

mysql> exit
Bye
$

Finally a note on the MySQL root password. In Ubuntu systems running MySQL 5.7 (and later versions), the MySQL root user is set to authenticate using the auth_socket plugin by default rather than with a password. However in securing MySQL (see Installation Manual for 2.15 on Ubuntu 20.04 Server#MySQL Security and Performance Issues) we had to set a password for the MySQL root user and that password was set to "wwadmin" even though it is not used.

Change the password for admin

Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (http://.../webwork2/admin) and myTestCourse (http://.../webwork2/myTestCourse) with Username "admin" and Password "admin". Then change the passwords from "admin" to something more secure.

Change the password for profa

Change the passwords for the WeBWorK user profa. Login to myTestCourse (http://.../webwork2/myTestCourse) with Username "profa" and Password "profa". Then change the passwords from "profa" to something more secure.

Change the password for jsmith

Change the passwords for the WeBWorK user jsmith if you want. jsmith is just a regular student so she can't do any real damage but you may still want to change the password. Login to myTestCourse (http://.../webwork2/myTestCourse) with Username "jsmith" and Password "jsmith". Then change the passwords from "profa" to something more secure.

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 edit the course.conf file for herself (for her own course) 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 WeBWoeK but it's 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 WeBWoeK but it's 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

$ cd /opt/webwork/webwork2/conf
$ gedit 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 or you can keep this set to localhost

Note that above we already set the password that WeBWorK uses when it communicates with the MySQL database. This is set with $database_password and it is not a bad idea to double check that it is correct.

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.

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 go to http://search.cpan.org/dist/DateTime-TimeZone/ . These timezones are more refined than standard timezone 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 DateTime::TimeZone::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 timezones 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

If you want WeBWorK questionnaires or similar things from different courses to be mailed to a central person or persons (e.g. the WeBWorK administrator), in defaults.config, you will see the lines

$mail{allowedRecipients}     = [
   #'prof1@yourserver.yourdomain.edu',
   #'prof2@yourserver.yourdomain.edu',
];

But we are not supposed to edit the defaults.config file, so if we want to do this, we will copy this to localOverrides.conf and edit it appropriately. Note that we should probably move this setting to the site.conf file.

Edit the localOverrides.conf file

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

As we said above, if you want WeBWorK questionnaires or similar things from different courses to be mailed to a central person or persons (e.g. the WeBWorK administrator), in localoverrides.config, add and then edit the lines

$mail{allowedRecipients}     = [
   #'prof1@yourserver.yourdomain.edu',
   #'prof2@yourserver.yourdomain.edu',
];

removing the # and using the professor(s) actual email address(es). In order to have professors from individual courses receive such email, this should be set in course.conf (which you find in the course directory) to the addresses of professors of each course. Note that the settings in course.conf override the settings in site.conf, default.conf and localOverrides.conf so if in addition you want e.g. the WeBWorK administrators to receive copies, you have to add them as well.

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.

Also now there are several versions of the classlist editor, homeworkset editor, library browser and pgproblem editor. Which ones are available in a course is determined by the settings for %showeditors in localOverrides.conf. As above, if you want to customize what is available for an individual course (e.g. one professor may want to try out the new editors and others may not), copy the %showeditors structure to course.conf and then edit it to make available the desired editors.

Set up WeBWorK to use SSL

This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. Follow the instructions at Installation_Manual_for_2.15_on_Ubuntu_20.04_Server#Implement Optional C (SSL)

Set up Access to Apache's server-info and servo-status

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

I suggest you allow access to server information from e.g. your department domain. To do this uncomment (i.e. remove the # from)

	Require ip 192.0.2.0/24

and then replace 192.0.2.0/24 by .math.yourschool.edu where of course you should edit .math.yourschool.edu appropriately.

Then save the file and quit (press ^X, Y, <Enter>).

Now we edit status.conf

$ cd /etc/apache2/mods-available
$ sudo nano status.conf
[sudo] password for wwadmin: <wwadmin password>

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 apache2ctl restart
password:<wwadmin password>

Test your server by connecting to "http://localhost/" and/or connecting to your server 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://localhost/server-status" using a browser on your machine or from a browser on a remote machine in the math.yourschool.edu domain.

Further test Apache by connecting to "http://localhost/server-info" using a browser on your machine (or or 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.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.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. 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 48932:tid 140494759132224] AH00489: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0 configured -- resuming normal operations

indicating that both mod_apreq2 and mod_perl are installed and running.

File and Directory Locations and System Information

This installation of WeBWorK and Ubuntu follows the instructions given in Installation_Manual_for_2.15_on_Ubuntu_20.04_Server. You can look there to find the locations of the WeBWorK files. All optional configurations (A-E) are implemented except that

Optional A is implemented with the wwtmp directory set up as a separate directory but not as a separate partition and
Optional C is not implemented. Optional C configures Apache (and optionally lighttpd) so that access to WeBWorK will

be through an encrypted connection (TLS/SSL) with an https: URL. You may have already implemented this.

All system files are in their standard Ubuntu locations. The Ubuntu installation is identical to that obtained from the Ubuntu 20.04 Server LiveDVD distribution (specifically ubuntu-20.04-live-server-amd64.iso).

Consult Category:Administrators for other WeBWorK documentation for system administrators.

Specific Virtual Environments

Below you will find additional information about installing the ova on other virtual environments.

VMware Workstation 15 Player running on a Windows 10 host

Importing the ova File

For VMware Player select Player, File, Open and then browse to the location of the WW2.15_Ubuntu20.04_Server.ova file and open the file.

You will get a warning message but on retry it will work (strange since the ova image was created on VMware Player).

Accessing your server from your host

From a Browser

Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the Apache2 Ubuntu Default Page. Lighttpd is also running (it is only used for internal WeBWorK calls) and you can test it by connecting to http://192.168.76.128:8080 and again you should see the Apache2 Ubuntu Default Page. Actually on my Windows 10 host, I can connect from Chrome, Firefox, and Brave but not from Edge. I haven't tried to figure out what is blocking Edge.

From a Terminal Emulator

I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.

Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.

And return to Set the Timezone for your server instructions above.

VMware Workstation 15 Pro

VirtualBox 6

The ova virtual machine image was created on VirtualBox 6 running on a Windows 10 host with the network adapter set to NAT and certain port forwarding rules in effect. Assuming you have not changed things when importing the image, some of these network setting may remain in effect (they will for VirtualBox running on a Windows host). See Other Virtual Environments below for more information. The port forwarding rules the image was created with are the following:

Port Forwarding
Name	Protocol	Host IP	Host Port	Guest IP	Guest Port
lighttpd	TCP	127.0.0.1	8080	10.0.2.15	8080
ssh	TCP	127.0.0.1	2222	10.0.2.15	22
ssh2	TCP	127.0.0.1	443	10.0.2.15	443
web	TCP	127.0.0.1	80	10.0.2.15	80

The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command

$ ip address show

and looking at the output, 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

(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 .

If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine (or from the terminal on the guest once you login). We have not yet installed openssh so the secure connections ssh and ssh2 don't work at this point. Assuming your WeBWorK server is set up as above, from a web browser running on your host machine connect to http://127.0.0.1/webwork2 (http://localhost/webwork2 also works) and you should see the "Welcome to WeBWorK!" page. If all you want to do is test out WeBWorK yourself without any other users, you are all set at this point but please read the rest of these instructions so that you understand how insecure your WeBWorK server is right now. Lighttpd is also running (it is only used for internal WeBWorK calls) and you can test it by connecting to http://127.0.0.1:8080/webwork2_files or http://localhost:8080/webwork2_files and you will see the WeBWorK Placeholder page.

-- Main.ArnoldPizer - 10 May 2020

Installing from WW2.15 Ubuntu20.04 Server Virtual Machine Image

Contents

Installing from WW2.15 Ubuntu20.04 Server Virtual Machine Image

Overview

Download the ova image

OVA and OVF Files

Installing the WeBWorK Virtual Machine Image

Processors, Memory, Hard Disk

Import the .ova File

Your Server

PGbasicmacros.pl

Boot your server

Log into your server

Install openssh-server

Accessing Your Server from a Terminal Emulator on your Host

Set the Timezone for your server

Checking for and installing hotfixes

System Configuration

Edit the site.conf file

The defaults.config file

Edit the localOverrides.conf file

Test that Things are Working Properly

Passwords

Change the password for wwadmin

Change the password for webworkWrite

Change the password for admin

Change the password for profa

Change the password for jsmith

System Configuration

Edit the site.conf file

The defaults.config file

Edit the localOverrides.conf file

Set up WeBWorK to use SSL

Set up Access to Apache's server-info and servo-status

File and Directory Locations and System Information

Specific Virtual Environments

VMware Workstation 15 Player running on a Windows 10 host

Importing the ova File

Accessing your server from your host

From a Browser

From a Terminal Emulator

VMware Workstation 15 Pro

VirtualBox 6

Navigation menu

Search