WeBWorK 2.20 Ubuntu Server 24.04 LTS Virtual Machine Image

These instructions cover the installation of the Ubuntu Server 24.04 LTS 64 bit operating system and WeBWorK 2.20 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.

Installing from WW2.20 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.20, 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.20 at Installation Manual for 2.20 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.20_Ubuntu24.04_Server.ova.sha256 and WW2.20_Ubuntu24.04_Server.ova The ova is a 8.2 GB file.

• WeBWorK Download Site

Verify the SHA256 checksum of your downloaded file WW2.20_Ubuntu24.04_Server.ova agrees with the one in WW2.20_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.20_Ubuntu24.04_Server.ova with the command

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

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

Installing the WeBWorK Virtual Machine Image

Import the file WW2.20_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. Hardware compatibility was set to "Workstation 16.x virtual machine". 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 with 2 cores each

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

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

Your server

After importing, your virtual WeBWorK server will be identical to a system created by following the instructions Installation Manual for 2.20 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.20 on Ubuntu in order to understand how your server has been set up. Especially look at Notation in the Installation Manual for 2.20 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.

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

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.20 on Ubuntu.