WeBWorK 2.19 Ubuntu Server 24.04 LTS Virtual Machine Image

From WeBWorK_wiki
Jump to navigation Jump to search


These instructions cover the installation of the Ubuntu Server 24.04 LTS 64 bit operating system and WeBWorK 2.19 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, QEMU/KVM, etc.

This image file has been tested on

  • VMware Workstation 17 Pro
  • VirtualBox 7
  • QEMU/KVM running on a Ubuntu 24.04 Desktop host

This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc.) installed and configured.

Contents

Installing from WW2.19 Ubuntu24.04 Server Virtual Machine Image

Overview

After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 24.04 LTS system with WeBWorK 2.19, Mjolicious/hypnotoad, MariaDB, R server, 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 MariaDB user webworkWrite who has access to MariaDB, for the WeBWorK users admin and admin1 who have admin privileges and for the WeBWorK user profa who has professor privileges and also the Mjolicious secret (see below).

There are more detailed instructions for Ubuntu Server 24.04 and WeBWorK 2.19 at Installation Manual for 2.19 on Ubuntu.

Download the ova image

Download the sha256 checksum and the .ova files from the WeBWorK Download Site below.

You want to download the files WW2.19_Ubuntu24.04_Server.ova.sha256 and WW2.19_Ubuntu24.04_Server.ova The ova is a 8.5 GB file.

Verify the SHA256 checksum of your downloaded file WW2.19_Ubuntu24.04_Server.ova agrees with the one in WW2.19_Ubuntu24.04_Server.ova.sha256.

OVA and OVF files

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

  • 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).
  • Possibly other files
  • 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 .ovf or .vmdk file will succeed.

You can extract the files in WW2.19_Ubuntu24.04_Server.ova with the command 

$  tar -xvf WW2.19_Ubuntu24.04_Server.ova

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

Installing the WeBWorK Virtual Machine Image

Import the file WW2.19_Ubuntu24.04_Server.ova into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 17 Pro running on a Windows 11 Pro host. It has been tested on

  • VMware Workstation 17 Pro running on a Windows 11 host (Pro edition)
  • VMware Workstation 17 Pro running on a Ubuntu 24.04 Desktop host
  • VirtualBox 7 running on a Windows 11 host (Pro editions)
  • VirtualBox 7 running on a Ubuntu 24.04 Desktop host
  • QEMU/KVM running on a Ubuntu 24.04 Desktop host

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

Processors, Memory, Hard Disk, Networking

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

  • 30 GB dynamically allocated disk drive in VMDK format (single file) of which 13 GB is used
  • 4 GB memory
  • 2 cpu

These resources are OK for testing and may suffice for a very small course but it is possible to overwhelm the machine.

Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 17 Player running on a Windows 11 host). You should adjust these resources either 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 is more complicated. See Specific Virtual Environments below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see Increase Disk Space below).

Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see (Specific Virtual Environments) and/or look at Debugging Networking Issues.

Import the .ova file

There may be specific information for your situation below. See

Your server

After importing, your virtual WeBWorK server will be identical to a system created by following the instructions Installation Manual for 2.19 on Ubuntu with the Webwork2 Mojolicious App being served directly via hypnotoad (option 1) and the Optional Configurations B and C implemented. Note that Option A (SSL) is not implemented (see Set up WeBWorK to use SSL 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.19 on Ubuntu in order to understand how your server has been set up. Especially look at Notation in the Installation Manual for 2.19 on Ubuntu to understand the notation we use in these instructions.

Boot Your Server

Log into your server

After booting 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. We will denote

wwadmin's password by <wwadmin password>. Initially this is set to wwadmin. If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.

Test your ip address

Run the command 

$ ip address show

and look 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 you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see (Specific Virtual Environments). If that doesn't help look at Debugging Networking Issues. You have to fix this before you can go on to the next step.

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 your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, 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. In any event, after testing, read the section Make the WeBWorK Configuration Permanent below. 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.

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:  Time zone: Etc/UTC (UTC, +0000)
...

which is probably not 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/New_York". Then set the timezone (you have to be root), e.g. 

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

and then 

$ timedatectl

to check it was set correctly.

Checking for and Installing Hotfixes

Follow the instructions at Check_for_and_Install_Hotfixes in the Installation Manual for 2.19 on Ubuntu.

Important: The are bug fixes for both the webwork2 code and the pg code that occurred after the virtual machine image was built. You should definitely update both the webwork2 and pg code.


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

Usually the "admin" user is added as an admin in all new courses and she can grant "admin" privileges to anyone (but she should be very careful in doing this).

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 network server setup. Search for 192.168.138.132 and replace that by your the new ip address you found above (192.168.76.128 in our example above).

But wait, this can be tricky. If you set up port forwarding (as we had to for VirtualBox), then instead use the code 

 $server_root_url   = 'http://127.0.0.1:8081';

The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM) 

$server_root_url   = 'http://192.168.76.128';

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

Remark. If this is not set correctly, then when you test the Library Browser, e.g. by clicking on Library Browser on the Main Menu, then on Open Problem Library (actually it should already be selected so it will be greyed out) and select a Subject, you may not be able to select a Chapter and you will see an error message similar to 

183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.

Or when you view problems in the Library Browser, they will not display correctly but when you "try" them by clicking on the "eye" symbol, they will display correctly. If you google this message, you will find a lot of people have seen this error and the most common reason is that $server_root_url has not been set correctly. A common error is to forget http:// or to use http:// when you should use https:// (or vice versa) or to just have the wrong domain name or ip address.

We now continue editing site.conf

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 two instances. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.

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

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

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

Then save the file and Quit. And restart the webwork2 app so that these changes take effect: 

$ sudo systemctl restart webwork2

The defaults.config file

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

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. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.

Follow the instructions at Implement Option A (SSL) in the Installation Manual for 2.19 on Ubuntu.

Note that the Virtual Machine Image was built using Option 1: Serving Directly via Hypnotoad so that in the instructions for setting up SSL follow the section Set up Hypnotoad to use SSL (Option 1).

Finish up

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. If you have already set up https and haven't setup the redirect, then you should use https://192.168.76.128/webwork2 . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.


We will test out a few important parts of WeBWorK. If you run into problems, you should look at the WeBWorK app error log which is located at /opt/webwork/webwork2/logs/webwork2.log. And you should look at Test that Things are Working Properly in the Installation Manual for 2.19 on Ubuntu for help.

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

Click on "myTestCourse" and login with login name "profa" and password "profa". Next you have to complete a two factor authentication process but you can select to skip it for future logins on your device if you wish. At this point you are a regular professor. There is also an administrator "admin", a second administrator "admin1", 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 Assignments on the Main Menu and click on Demo. Then look at the problems. Mathematical equations should be typeset. Continue looking at problems to see if everything is working properly. Look through the problems in the other sets.

Next click on Problem List to bring back the Problem List Page and click on Download Hardcopy .... 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.

Look through the problems in the other sets.

Now test the Library Browser. 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.

Next test that WeBWorK problems using R run properly. You are already in the Library Browser. Select "Statistics" as Subject, "Bayesian inference" as Chapter and "Posterior distribution" as Section and then hit View Problems. If the problems display with no error messages, all should be well. 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.

If you are new to WeBWorK or even if you are a pro, you should probably log in as a student to see what the student interface looks like. It's much simpler than the professor or admin interfaces. Login with login name "jsmith" and password "jsmith". The "admin" view is very similar to the "prof" view but you have the ability to change things about the course that mere professors do not have. Finally you can click on "Guest Login" and see what that looks like.

Make the WeBWorK Configuration Permanent

Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with ip address show) and used that when editing the site.conf file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.

  1. The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the site.conf file.
  2. The other method is to setup networking to use a fixed specific ip address for your server and use that in the site.conf file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the Networking section under VirtualBox 6 running on a Windows 11 host below for information on editing these files. You can search the web for information on the correct syntax to use.

Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections Edit the site.conf file and Edit the localOverrides.conf file.

Remember that any time you edit WeBWorK's configuration files, you have the restart the WeBWorK2 app for the changes to take effect; see Enable_and_start_the_Webwork2_Systemd_Service in the Installation Manual for 2.19 on Ubuntu. For networking changes to take effect, you should reboot the server.

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. 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. Finally you definitely should CHANGE THE PASSWORD or DELETE the WeBWorK user admin1 who has admin privileges both in the admin course and in the myTestCourse. Otherwise anyone can connect to WeBWorK server and pretty easily gain access and do anything they want. Also change the mojolicious.yml secret.

Change the mojolicious.yml secret

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

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. Below when we refer to <wwadmin password>, we mean the new <wwadmin password>.

Change the password for webworkWrite

Now we change the passwords for the MariaDB 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 webwork2 so the changes take effect. 

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

and start MariaDB 

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

You should see 

Welcome to the MariaDB monitor ...
MariaDB>

Now lets check the MariaDB users. 

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

You will see a table with four users. webworkWrite should have a valid password (which will be displayed in encrypted form).

Now we will change the password for the webworkWrite User 

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

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

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

Then exit MariaDB 

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

Now exit 

MariaDB> exit
Bye
$

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". You have to complete a two factor authentication process but you can select to skip it for future logins on your device if you wish. Then change the passwords from "admin" to something more secure. Note that in WeBWorK to change the password of the user you are logged in as, select "Account Settings" in the "MAIN MENU".

Change the password for admin1

The WeBWorK user admin1 was used to setup the system and because two factor authentication was used, no one should be able to login as admin1 but it is safer and cleaner to either delete the admin1 account or change the password for admin1. Login to both the WeBWorK admin course (http://.../webwork2/admin) and myTestCourse (http://.../webwork2/myTestCourse) with Username "admin" and Password "admin". Select the "Accounts Manager", edit the user admin1, check the box next to the "password set" box (which deletes the password) and hit "Save Edit". Then edit the user admin1 again and enter a password much more secure than admin1. Or you can just delete the admin1 account. Remember to do this for BOTH courses.

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. Or you can login as "admin" and use the "Accounts Manager" to change the password.

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 "jsmith" to something more secure. Or you can login as "admin" or "profa" and use the "Accounts Manager" to change the password.

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.

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.

Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits

Look at Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server and adjust "clients", "workers" and "spare" in the file /opt/webwork/webwork2/conf/webwork2.mojolicious.yml according to the rule of thumb given there. You may also have to adjust the number of database connections, see Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server

Increase disk space

This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in Specific Virtual Environments below. The second step is to repartition the disk and expand the file system. Let us assume you have completed the first step and expanded the disk capacity from it's initial 20 GB to 30GB although in practice you will probably want to make it larger. First enter 

$ df -h
Filesystem      Size  Used Avail Use% Mounted on
...
/dev/sda2        19G   11G  7.3G  59% /
...

to see how much disk space we have initially. Now run parted as root: 

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

and you will see something like 

GNU Parted 3.3
Using /dev/sda
Welcome to GNU Parted! Type 'help' to view a list of commands.
(parted)

Now enter the "print" command 

(parted) print
Model: VMware, VMware Virtual S (scsi)
Disk /dev/sda: 21.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:   

Number  Start   End     Size    File system  Name  Flags
 1      1049kB  2097kB  1049kB                     bios_grub
 2      2097kB  20.0GB  20.0GB  ext4

(parted)

We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command 

(parted) resizepart
Partition number? 2
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?
Yes/No? Yes
End?  [20GB]? 30GB
(parted)

Now enter the "print" command again 

(parted) print
Model: VMware, VMware Virtual S (scsi)
Disk /dev/sda: 31.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number  Start   End     Size    File system  Name  Flags
 1      1049kB  2097kB  1049kB                     bios_grub
 2      2097kB  30.0GB  30.0GB  ext4

(parted)

Notice we now have a 30 GB disk. Now quit parted. 

(parted) quit
Information: You may need to update /etc/fstab.

Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below 

$  sudo resize2fs /dev/sda2
[sudo] password for wwadmin: <wwadmin password>
resize2fs 1.45.5 (07-Jan-2020)
Filesystem at /dev/sda2 is mounted on /; on-line resizing required
old_desc_blocks = 2, new_desc_blocks = 3
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.

and run df -h and we should see something like 

$ df -h
Filesystem      Size  Used Avail Use% Mounted on
...
/dev/sda2        29G  11G  18G  38% /
...

indicating that we now a lot more space on our disk. Yea!

File and Directory Locations and System Information

This installation of WeBWorK and Ubuntu follows the instructions given in Installation_Manual_for_2.17_on_Ubuntu. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.

  • Option A is not implemented. Option A configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.

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

Known Issues

Here are the known issues with this release.

PGbasicmacros.pl

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

If you do what to proceed with the fix 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.

Specific Virtual Environments

Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of the specific environments we have information on:

VMware Workstation 17 Pro running on a Windows 11 host

Importing the ova File

For VMware Workstation Pro select File, Open and then browse to the location of the WW2.19_Ubuntu24.04_Server.ova file and open the file. Name your machine and select a storage path and then hit Import

Now continue reading the instructions in the section Boot Your Server above.

Networking

Networking should work right out of the box.

Accessing your server from your host

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 .

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 WeBWorK Placeholder Page. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the WeBWorK Welcome page.

Note that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the WeBWorK configuration above. At this point you should just continue reading here about connecting from a terminal emulator.

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.

Expand the disk drive

Make sure your server is powered off and open VMware Workstation 17 Pro. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.

You still have to repartition the disk and expand the file system on you guest. For that see Increase disk space above.

Continue the Installation

Return to the Accessing Your Server from a Terminal Emulator on your Host instructions above.

VirtualBox 7 running on a Windows 11 host

Importing the ova File

For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the WW2.19_Ubuntu24.04_Server.ova file and open the file. Click Finish. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.

Now continue reading the instructions in the section Boot Your Server above.

Networking

Initially networking will be broken. Do the following from your guest WeBWorK system 

$ sudo lshw -C network
[sudo] password for wwadmin: <wwadmin password>

and you will see something like 

      ...
      logical name: enp0s17
      version: 02
      serial: 08:00:27:30:28:b6
      ...

Remember the logical name from your system as we will need it below. We have to backup and then edit one file. 

$ cd /etc/netplan/
$ sudo cp  50-cloud-init.yaml  50-cloud-init.yaml.bak1
[sudo] password for wwadmin: <wwadmin password>

Now edit the 50-cloud-init.yaml file (note that on a Ubuntu host I had to enlarge the window to see the text) 

$ sudo nano  50-cloud-init.yaml

It should look like: 

# This file is ...
network:
  ethernets:
    ens33:
      dhcp4: true
  version: 2

Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.


Now reboot your server,e.g. 

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

login and run the command 

$ ip address show

and look at the output, something like 

... 
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
   link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff
   inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17
...

We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below.

In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network" Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:

Port Forwarding
Name Protocol Host IP Host Port Guest IP Guest Port
ssh TCP 127.0.0.1 2222 10.0.2.15 22
https TCP 127.0.0.1 4443 10.0.2.15 443
http TCP 127.0.0.1 8081 10.0.2.15 80

Double check that you have entered everything correctly (using your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".

Now boot your server.

Accessing your server from your host

We need to employ the port forwarding rules above.

From a browser

Assuming your WeBWorK server is set up as above with ip address 127.0.0.1:8081, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the WeBWorK Placeholder Page. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and after a few seconds you should see the WeBWorK Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.

Note that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the WeBWorK configuration above. At this point you should just continue reading here about connecting from a terminal emulator.

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 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. 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 WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.

Expand the disk drive

Make sure your guest is shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list (probably "WW2.18_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. Click “Apply” when you're done.

You still have to repartition the disk and expand the file system on you guest. For that see Increase disk space above.You still have to repartition the disk and expand the file system on you guest. For that see Increase disk space above.

Continue the Installation

Return to the Accessing Your Server from a Terminal Emulator on your Host instructions above.

VMware Workstation 17 Pro running on a Ubuntu 24.04 Desktop host

Importing the ova File

For VMware Player select File, Open a Virtual Machine and then browse to the location of the WW2.19_Ubuntu24.04_Server.ova file and import the file.

Now continue reading the instructions in the section Boot Your Server above.

Networking

Networking should work right out of the box.

Accessing your server is exactly the same as in VMware Workstation 17 Pro running on a Windows 11 host above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g. 

$ ssh wwadmin@192.168.76.128

where of course you need to use the ip address of your WeBWorK guest server.

Now login to your server using the password "wwadmin".

Expand the disk drive

Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.

You still have to repartition the disk and expand the file system on you guest. For that see Increase disk space above.

Continue the Installation

Return to the Accessing Your Server from a Terminal Emulator on your Host instructions above.

VirtualBox 7 running on a Ubuntu 24.04 Desktop host

Importing the ova File

Importing the ova File is exactly the same as in VirtualBox 7 running on a Windows 11 host above.

Now continue reading the instructions in the section Boot Your Server above.

Networking

Accessing your server involves the same procedure as in VirtualBox 7 running on a Windows 11 host above. So you have to

  1. Find the name of the virtual nic (network interface card)
  2. Edit 50-cloud-init.yaml
  3. Reboot your WeBWorK guest
  4. Find your WeBWorK guest's ip address
  5. Set up port forwarding

See VirtualBox 7 running on a Windows 11 host above for details.

Except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g. 

$ ssh -p 2222 wwadmin@127.0.0.1

Now login to your server using the password "wwadmin".

Expand the disk drive

The procedure is the same as in Expand the disk drive the Windows 11 case above.

You still have to repartition the disk and expand the file system on you guest. For that see Increase disk space above.

Continue the Installation

Return to the Accessing Your Server from a Terminal Emulator on your Host instructions above.

QEMU/KVM running on a Ubuntu 24.04 Desktop host

First install Qemu-KVM

It is probably a good idea to first update and upgrade the system packages: 

$ sudo apt update
$ sudo apt upgrade

Now install Qemu-KVM 

$ sudo apt install -y qemu-kvm virt-manager libvirt-daemon-system virtinst libvirt-clients bridge-utils

Enable and start libvirtd 

$ sudo systemctl enable --now libvirtd
$ sudo systemctl start libvirtd

and check that all is OK 

$ sudo systemctl status libvirtd

Now add wwadmin to the kvm and libvirt groups. 

$ sudo usermod -aG kvm $USER
$ sudo usermod -aG libvirt $USER

Convert the image to qcow2 format

cd to whatever directory you downloaded the WW2.19_Ubuntu24.04_Server.ova file to (maybe "Downloads") and then untar it 

tar -xvf WW2.19_Ubuntu24.04_Server.ova

which might take awhile. Then run the command to covert the vmdk format to qcow2 format 

qemu-img convert -p -f vmdk -O qcow2 WW2.19_Ubuntu24.04_Server-disk1.vmdk WW2.19_Ubuntu24.04_Server.qcow2

and move the qcow2 image to the correct location 

sudo mv WW2.19_Ubuntu24.04_Server.qcow2 /var/lib/libvirt/images/

Boot up your virtual machine

Start up Virtual Machine Manager (search for VM in the app manager). Note that if you run into problems running the Virtual Machine Manager (e.g. QEMU/KVM not connected), the first thing to try is rebooting your host machine.

In the Virtual Machine Manager, select File, New Virtual Machine, Import existing disk image, Forward, Browse and finally select WW2.19_Ubuntu24.04_Server.qcow2. Then select Choose Volume and enter Ubuntu 24.04 LTS for the operating system you are installing. Next click Forward and choose your memory and CPUs. Select Forward again, name your system and finally select finish.

Now log into your virtual machine (wwadmin with password wwadmin)

Networking

Accessing your server involves the same procedure as in VirtualBox 7 running on a Windows 11 host above. So you have to

  1. Find the name of the virtual nic (network interface card), probably something like enp1s0
  2. Edit 50-cloud-init.yaml
  3. Reboot your WeBWorK guest
  4. Find your WeBWorK guest's ip address

See VirtualBox 7 running on a Windows 11 host above for details except that

  1. You do not need port forwarding
  2. Instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.
$ ssh  wwadmin@192.168.122.233

(where of course you need to use the actual ip address of your guest WeBWorK server).

Expand the disk drive

You can do most of this from the graphical Virtual Machine Manager (select the machine, then Edit, Virtual Machine Details). Below are commands to this from the command line. I think you have to actually expand the disk from the command line but you can get information and add cpu's and/or memory from the graphical Virtual Machine Manager.

I'm assuming the name of your WeBWorK guest is wwserver and it is Shutoff. First find the location of the disk. Run the command 

$ sudo virsh domblklist wwserver
[sudo] password for wwadmin: <wwadmin password>

and you will see something like 

 Target   Source
-------------------------------------------------------------------------
 sda      /var/lib/libvirt/images/WW2.19_Ubuntu24.04_Server-disk1.qcow2

Now get some info about the disk 

$ sudo qemu-img info /var/lib/libvirt/images/WW2.19_Ubuntu24.04_Server-disk1.qcow2
[sudo] password for wwadmin: <wwadmin password>

and you will see something like 

image: /var/lib/libvirt/images/WW2.19_Ubuntu24.04_Server-disk1.qcow2
file format: qcow2
virtual size: 12 GiB (12884901888 bytes)
disk size: 6.76 GiB
cluster_size: 65536
Format specific information:
    compat: 1.1
    lazy refcounts: false
    refcount bits: 16
    corrupt: false

and now lets resize it to 20 GB by adding 8 GB 

sudo qemu-img resize /var/lib/libvirt/images/WW2.19_Ubuntu24.04_Server-disk1.qcow2 +8G
[sudo] password for wwadmin: <wwadmin password>
Image resized.

You still have to repartition the disk and expand the file system on you guest. For that see Increase disk space above.

Continue the Installation

Return to the Accessing Your Server from a Terminal Emulator on your Host instructions above.

Amazon EC2

While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the WeBWorK_2.19_Ubuntu_Server_24.04_LTS_Amazon_Machine_Image is faster and easier.

Debugging Networking Issues

If after reading the information above on networking you are still having problems, maybe the information below will be of help.

One method

There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms: 

$ ip address show

does not return an ip address and the WW guest can not access the outside world.

In VirtualBox I built another guest from the ubuntu-22.04-live-server-amd64.iso using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by 

sudo lshw -C network
[sudo] password for wwadmin: <wwadmin password>

specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files 

/etc/netplan/00-installer-config.yaml

and 

/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg

BUT in the WW guest the information did not agree. This led to the information given in the Networking section of VirtualBox 7 running on a Windows 11 host above.

Ports on your WeBWorK guest

Run the command 

$ sudo lsof -i -P -n | grep LISTEN
[sudo] password for wwadmin: <wwadmin password>

and you see something like 

systemd-r  697 systemd-resolve   13u  IPv4  19596      0t0  TCP 127.0.0.53:53 (LISTEN)
sshd       772            root    3u  IPv4  21834      0t0  TCP *:22 (LISTEN)
sshd       772            root    4u  IPv6  21845      0t0  TCP *:22 (LISTEN)
lighttpd   810        www-data    4u  IPv4  22509      0t0  TCP *:8080 (LISTEN)
mysqld     856           mysql   31u  IPv6  23312      0t0  TCP *:33060 (LISTEN)
mysqld     856           mysql   33u  IPv4  23654      0t0  TCP 127.0.0.1:3306 (LISTEN)
Rserve     865      rserveuser    3u  IPv4  22878      0t0  TCP 127.0.0.1:6311 (LISTEN)
/usr/sbin  946            root    4u  IPv6  21273      0t0  TCP *:80 (LISTEN)
/usr/sbin  956        www-data    4u  IPv6  21273      0t0  TCP *:80 (LISTEN)
/usr/sbin  957        www-data    4u  IPv6  21273      0t0  TCP *:80 (LISTEN)
/usr/sbin  958        www-data    4u  IPv6  21273      0t0  TCP *:80 (LISTEN)
/usr/sbin  959        www-data    4u  IPv6  21273      0t0  TCP *:80 (LISTEN)
/usr/sbin  960        www-data    4u  IPv6  21273      0t0  TCP *:80 (LISTEN)

Ports on your Windows 11 Pro host

Open a Power Shell command window as an administrator and run the command (it can take awhile) 

PS C:\> netstat -ab

Active Connections

 Proto  Local Address          Foreign Address        State
 TCP    0.0.0.0:135            desktop:0              LISTENING
 RpcSs
[svchost.exe]
 TCP    0.0.0.0:443            desktop:0              LISTENING
[vmware-hostd.exe]
 TCP    0.0.0.0:445            desktop:0              LISTENING
Can not obtain ownership information
 TCP    0.0.0.0:903            desktop:0              LISTENING
[vmware-authd.exe]
 TCP    0.0.0.0:913            desktop:0              LISTENING
[vmware-authd.exe]
 TCP    0.0.0.0:2869           desktop:0              LISTENING
Can not obtain ownership information
 TCP    0.0.0.0:3306           desktop:0              LISTENING
[mysqld.exe]
  ...
 TCP    0.0.0.0:6000           desktop:0              LISTENING
[XWin_MobaX.exe]
 TCP    0.0.0.0:49664          desktop:0              LISTENING
...
 TCP    127.0.0.1:2222         desktop:0              LISTENING
[VirtualBoxVM.exe]
 TCP    127.0.0.1:2222         desktop:52916          ESTABLISHED
[VirtualBoxVM.exe]
 TCP    127.0.0.1:2222         desktop:52917          ESTABLISHED
[VirtualBoxVM.exe]
 TCP    127.0.0.1:4443         desktop:0              LISTENING
[VirtualBoxVM.exe]
...

Ports on your Linux host

Run the command 

$ sudo lsof -i -P -n | grep LISTEN
[sudo] password for ****:

and you should see something like the following 

systemd-r   436 systemd-resolve   13u  IPv4  18620      0t0  TCP 127.0.0.53:53 (LISTEN)
vmware-au  1284            root   10u  IPv6  33012      0t0  TCP *:902 (LISTEN)
vmware-au  1284            root   11u  IPv4  33013      0t0  TCP *:902 (LISTEN)
sshd       8786            root    3u  IPv4 114131      0t0  TCP *:22 (LISTEN)
sshd       8786            root    4u  IPv6 114133      0t0  TCP *:22 (LISTEN)
cupsd     12124            root    6u  IPv6 138503      0t0  TCP [::1]:631 (LISTEN)
cupsd     12124            root    7u  IPv4 138504      0t0  TCP 127.0.0.1:631 (LISTEN)
VirtualBo 17065         wwadmin   48u  IPv4 185297      0t0  TCP 127.0.0.1:8081 (LISTEN)
VirtualBo 17065         wwadmin   49u  IPv4 185298      0t0  TCP 127.0.0.1:4443 (LISTEN)
VirtualBo 17065         wwadmin   50u  IPv4 185299      0t0  TCP 127.0.0.1:8080 (LISTEN)
VirtualBo 17065         wwadmin   51u  IPv4 185300      0t0  TCP 127.0.0.1:2222 (LISTEN)

Notice that port forwarding for VirtualBox has been set up correctly.


-- Main.ArnoldPizer - August 2024

Retrieved from "https://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.19_Ubuntu_Server_24.04_LTS_Virtual_Machine_Image&oldid=24781"