WeBWorK

Prerequisites

You need an active Azure subscription, an SSH key pair, and a VNet with a subnet in the target region.

Standard_B2ms (2 vCPU / 8 GiB RAM) is a good starting size. For larger cohorts, choose a larger size and raise the Hypnotoad workers count in /opt/webwork/webwork2/conf/webwork2.mojolicious.yml.

Configure the network security group (NSG) to allow inbound 22/tcp from your management network, and 80/tcp from your users. Add 443/tcp once you enable HTTPS.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for WeBWorK by SecureAnyCloud, and select Create.

On the Basics tab, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22) and HTTP (80).

Review the two dedicated data disks on the Disks tab, then select Review + create and Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name webwork \
  --image <marketplace-image-urn> \
  --size Standard_B2ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_rsa.pub \
  --public-ip-sku Standard

Open HTTP to your users:

az vm open-port --resource-group <your-rg> --name webwork --port 80

Step 3 - Connect to your VM

Connect to the VM over SSH as azureuser.

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

WeBWorK runs as four systemd units: nginx, mariadb, webwork2 (the Hypnotoad app) and webwork2-job-queue (the Minion worker). The login page is served at /webwork2/. Check that all four are active:

systemctl is-active nginx mariadb webwork2 webwork2-job-queue curl -s -o /dev/null -w 'login page -> HTTP %{http_code}\n' http://127.0.0.1/webwork2/

The expected output is:

active active active active login page -> HTTP 200

Step 5 - Retrieve your administrator credentials

On first boot, the image generates a unique WeBWorK admin password, MariaDB password and Mojolicious session secret. There is no shipped default login. The image writes them to a root-only file. Read it with sudo:

sudo cat /root/webwork-credentials.txt

The file lists the admin username (admin), the generated admin password, the admin and demo course URLs, and the database credentials. All of them are unique to this VM.

Step 6 - Sign in to the admin course

Browse to http://<vm-public-ip>/webwork2/admin and sign in with the username admin and the password from the credentials file.

The admin course is the site console. From here you create, rename, archive and manage courses, manage accounts, and send email.

# Prove the generated admin credentials authenticate (from the VM):
CJ=$(mktemp)
curl -s -c "$CJ" -o /dev/null http://127.0.0.1/webwork2/admin
curl -s -b "$CJ" -c "$CJ" -o /dev/null \
  --data-urlencode "user=admin" \
  --data-urlencode "passwd=<WEBWORK_ADMIN_PASSWORD>" \
  --data-urlencode "submit=Login" \
  http://127.0.0.1/webwork2/admin
curl -s -b "$CJ" http://127.0.0.1/webwork2/admin | grep -qi 'Log ?Out' && echo "admin login OK" || echo "login check" rm -f "$CJ"

Step 7 - Explore the demo course and a rendered problem

The image ships a demo course with an assigned problem set (DemoProblems), so a fresh VM shows a real, MathJax-rendered WeBWorK problem straight away.

From the admin console, or by browsing to http://<vm-public-ip>/webwork2/demo, open DemoProblems, then Problem 1. WeBWorK renders the problem with MathJax. It also offers the instructor tools to preview, check and submit answers, and to act as any student.

To build your own course, select Add Course in the admin console. Then import problem sets from the Library Browser (the Open Problem Library is already indexed) or upload your own PG files.

Step 8 - Confirm the versions, the library and the data tiers

Check the installed versions, the Open Problem Library and the data disks:

echo "webwork2 $(sed -n 's/.*=//p' /opt/webwork/webwork2/VERSION | tr -d ' \";' | head -1)" echo "pg $(sed -n 's/.*=//p' /opt/webwork/pg/VERSION | tr -d ' \";' | head -1)" mariadb webwork -e "SELECT COUNT(*) AS opl_problems FROM OPL_pgfile;" 2>/dev/null df -h /var/lib/mysql /opt/webwork | grep -v Filesystem

The database lives on the dedicated /var/lib/mysql data disk. The application, PG, OPL and courses live on the /opt/webwork data disk. Both disks are captured into the image and re-provisioned with every VM.

Administration from the CLI

WeBWorK ships command-line tools under /opt/webwork/webwork2/bin. Run them as the web user. For example, to rotate a user's password:

sudo -u www-data WEBWORK_ROOT=/opt/webwork/webwork2 PG_ROOT=/opt/webwork/pg \
  /opt/webwork/webwork2/bin/newpassword <course> <user> <new-password>

Create a course with bin/addcourse. Refresh the Open Problem Library index with SKIP_UPLOAD_OPL_STATISTICS=1 bin/OPL-update. The demo course's sample problem is at /opt/webwork/courses/demo/templates/sacDemo/demoProblem1.pg.

Enabling HTTPS

For production, put a certificate in front of nginx. Point an A record at the VM and open 443/tcp in the NSG. Then install certbot and request a certificate for your DNS name:

sudo snap install --classic certbot
sudo certbot --nginx -d your-domain.example.edu

Next, set $server_root_url to your https:// URL and set $CookieSecure = 1; in /opt/webwork/webwork2/conf/localOverrides.conf. Restart with sudo systemctl restart webwork2.

Two-factor authentication (TOTP) is available but opt-in. To require it, set $twoFA{enabled} = 1; (or a list of course IDs) in localOverrides.conf and restart webwork2.

Backup and maintenance

• Database: run mysqldump webwork > webwork-backup.sql, or snapshot the /var/lib/mysql data disk.
• Courses and problems: back up /opt/webwork/courses, which is on the /opt/webwork data disk.
• OS updates: unattended-upgrades is enabled. Apply the rest with sudo apt update && sudo apt upgrade.
• Restart the app: run sudo systemctl restart webwork2 webwork2-job-queue.

Support

SecureAnyCloud maintains this image and provides 24/7 support. For help, contact the SecureAnyCloud support channel associated with your Marketplace subscription.

Deploy on Azure

Launch WeBWorK 2 on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com