WeBWorK 2.19 Ubuntu Server 24.04 LTS Amazon Machine Image
These instructions cover setting up WeBWorK 2.19 using the WeBWorK 2.19 on Ubuntu Server 24.04 LTS AMI (Amazon Machine Image).
This 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
- 1 Setting up the WeBWorK 2.19 Ubuntu Server 24.04 LTS Amazon Machine Image
- 2 Launch Your Server
- 3 Checking for and Installing Hotfixes
- 4 Give your Instance a permanent IP address
- 5 WeBWorK Configuration
- 6 Test that Things are Working Properly
- 7 Set up WeBWorK to use SSL
- 8 Finish up
- 9 Passwords
- 10 More House Keeping
- 11 File and Directory Locations and System Information
- 12 Known Issues
Setting up the WeBWorK 2.19 Ubuntu Server 24.04 LTS Amazon Machine Image
Overview
After using the WeBWorK 2.19 on Ubuntu Server 24.04 LTS Amazon 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.
It is imperative that you CHANGE THE PASSWORDS for the OS user wwadmin (who owns most WeBWorK files), 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). Finally you should set up SSL (https) access to WeBWorK if students will be using your server.
There are more detailed instructions for Ubuntu Server 24.04 and WeBWorK 2.19 at Installation Manual for 2.19 on Ubuntu. The AMI (Amazon Machine Image) was built following those instructions.
First you need an AWS account
First you need an Amazon AWS account. If you do not already have an account see https://aws.amazon.com/free/ and sign up for a free account. Or look at https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/.
Find the AMI image
Sign in to the AWS Management Console (https://signin.aws.amazon.com/) and search for "EC2 Dashboard". You will be taken to the Amazon EC2 console. From the navigation bar (at the top of the page), select the "US East (Ohio) us-east-2" region. You can select any Region that's available to you, regardless of your location but the AMI image is stored in the US East (Ohio) region so you have to use that one. In the navigation pane (to the left) under IMAGES, select AMIs. Then to the left of the search bar, select "Public images" (the choices are "Owned by me", "Public images", "Private images") and in the search bar enter "WeBWorK". You should see WeBWorK 2.19 on Ubuntu Server 24.04 LTS listed.
NOTE: If for whatever reason you can not or do not want to use the US East (Ohio) region, you can copy the AMI to another region. See https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/CopyingAMIs.html#ami-copy-steps or google "copy ami from one region to another".
Configure the WeBWorK AMI Image
Select the WeBWorK 2.19 on Ubuntu Server 24.04 LTS AMI and hit Launch instance from AMI
Name and tags
Name the instance and add additional tags if you want.
Choose an Instance Type
Information on ec2 instance types can be found at https://aws.amazon.com/ec2/instance-types/. I would suggest you look at t2 or t3 Instances.
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources:
- 30 GB disk drive of which about 8 GB is used
- 2 GB memory
- 2 (virtual) cpu
The above resources are minimal. These resources are OK for testing but it is possible to overwhelm the machine. This may happen e.g. if you want to simultaneously display many problems in the Library Browser or if you have several simultaneous users. If this happens your options are to wait until the server recovers or reboot the server.
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources:
- 70 GB disk drive
- 32 GB memory
- 8 (virtual) cpu's
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020.
Most likely the resources required for your server will fall within the range from small to 2xlarge. You can always change the resources available to an instance (see Changing the instance type below) but for this you will have to stop the instance. For this reason it is best to start with reasonable resources. For a server that you will be using with students it might be reasonable to start with a small or medium instance. But of course this is highly dependent on the number of students who will be using the server simultaneously.
Select or Create a key pair
A key pair is used to securely log into your server. Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).
Network Settings
You can create a security group or use an existing one.
You also should create inbound rules so that you and others can communicate with your server instance.
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source 0.0.0.0/0. This means, as the warring states: "Rules with source of 0.0.0.0/0 allow all IP addresses to access your instance" but of course no one can login unless they have the appropriate credentials. You can restrict this to a specific workstation (e.g. 98.12.176.149/32) or a range (e.g.98.12.176.0/24) of ip addresses (e.g. workstations on your network). If you select "My IP", you will only be able to connect from your workstation which is good for security but maybe not convenience. You can always add other rules to SSH in from other workstations.
SSH TCP 22 98.12.176.149/32 SSH for admin
You should allow HTTP (port 80). Initially for testing you may want to restrict these but for a production machine you would want to allow access from anywhere, i.e. 0.0.0.0/0. Note that except for guest users who have very limited access if you allow them at all, no one can log into WeBWorK on your server without a password. But see the section Passwords below for information on users who already have simple non secure passwords that must be changed.
You should also allow HTTPS although initially your server will not be setup for this.
Important If you do not see information about adding SSH (port 22) or HTTP (port 80) and/or HPPTS (port 443), select "Edit" next to "Networking" and add the required "Inbound Security Group Rules".
If you have problems connecting to your server, see the section Connection Problems below.
Configure storage
You can change the amount of disk space. 30 GB is a reasonable amount to start with for a small server.
Launch Your Server
Click "Launch instance" to launch your instance
Now Launch your server by clicking on "Launch instance". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "Instances"
On your EC2 Dashboard (EC2 Management Console), find the Public IPv4 address, say 18.216.251.98. We will use this in our examples. Obviously you should substitute your own.
Accessing Your Server from a Terminal Emulator on your Host
You can login to your server using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favorite terminal emulator. Note that I had to update my terminal emulator (MobaXterm) in order to connect. I recommend you use the latest version of your favorite terminal emulator.
If you use a terminal emulator like MobaXterm use the Advanced SSH Settings to use the WWsecretkey.pem file as your private key. Check the "private key" box, search for WWsecretkey.pem and then connect to 18.216.251.98 and login as ubuntu (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar.
If you are using ssh in a terminal window, use the command
ssh -i WWsecretkey.pem ubuntu@18.216.251.98
(you may have to provide the path to the WWsecretkey.pem file). Note that the permission on the WWsecretkey.pem file is required to be set so that the file is not readable by others. You need something like
chmod 600 WWsecretkey.pem
If you are using a bash shell running on Ubuntu under Windows 10, you may find it impossible to change the permission of WWsecretkey.pem. In that case copy WWsecretkey.pem to your home directory and change the permission there. From the directory containing WWsecretkey.pem
cp WWsecretkey.pem ~/ cd chmod 600 WWsecretkey.pem ssh -i WWsecretkey.pem ubuntu@18.216.251.98
Connection Problems
If you have problems connecting the first thing to check is that ports 22 (and 80 and 443) are open for inbound connections and are accessible from your location. From the EC2 dashboard, select "Instances", click on the "Instance ID" number, select the "Security" tab, and look under "Inbound rules". Check that ports 22, 80 and 443 are open and are accessible from your location (e.g. "Source" 0.0.0.0/0 indicates your instance is accessible from everywhere but of course the proper credentials are necessary to connect). If a rule needs to be added or edited, select the "Security groups" number, "Edit inbound rules" and then edit and/or "Add rule".
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html for further help.
Users on your system
There are two users who can login to the system: ubuntu and wwadmin
ubuntu
ubuntu is the "system" user who has sudo privileges. You probably always want to initially log in as ubuntu using the secret key file WWsecretkey.pem.
Running commands as root
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the sudo command while logged in as ubuntu.
To run commands as root use
$ sudo <command>
A log of all sudo commands is kept in /var/log/auth.log .
You can also use sudo to become root and get the root prompt # although this is not recommended as it can be dangerous. To do this run
$ sudo -s #
When you want to exit the root prompt and return to being the regular user ubuntu, do the following
# exit exit $
wwadmin
wwadmin is the "WeBWorK" administrator user who owns most of the WeBWorK system files. For example if you want to edit some WeBWorK file, you should use the su (switch user) command to become wwadmin. The password for wwadmin is "wwadmin" so the command is:
$ su wwadmin Password: wwadmin $
After you have finished whatever you have to do as wwadmin, you can return to being the ubuntu user by
$exit exit $
wwadmin is not in the sudo group so if you want to use sudo, you have to be ubuntu.
Also you should change the password for wwadmin to something much more secure than "wwadmin" (see Passwords).
Set the Timezone for your server
To find out what timezone your server is set to run the command
$ timedatectl
and you will see
... Time zone: America/New_York (EDT, -0400) ...
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/Los_Angeles". Then set the timezone (you have to be root), e.g.
$ sudo timedatectl set-timezone America/Los_Angeles
and then
$ timedatectl
to check it was set correctly.
Checking for and Installing Hotfixes
To check for and/or install updates you will have to become the wwadmin user:
$ su wwadmin Password: wwadmin $
Then follow the instructions at Check for and Install Hotfixes in the Installation Manual for 2.19 on Ubuntu. Remember that you have to switch back to the ubuntu user and restart the webwork2 app after updating the webwork2 and/or pg code.
$ exit $ sudo systemctl restart webwork2
Important: The are bug fixes for both the webwork2 code and the pg code that occurred after the AMI was built. You should definitely update both the webwork2 and pg code.
Give your Instance a permanent IP address
As currently set up if you stop your instance (e.g. to change resources) when you restart it, the instance will have a new IP address, which means you will have to change the network setup. To fix this situation, go to your EC2 panel and in the left panel under "Network & Security", select "Elastic IPs". Then select "Allocate Elastic IP address", and hit "Allocate". For example, assume 18.190.3.215 was allocated. Now select your newly allocated IPv4 address and under "Actions", select "Associate Elastic IP address" and then "Choose an instance" (your instance!) and hit "Associate". Now the ip address 18.190.3.215 is permanently associated with your instance. Note that on your terminal emulator you will have to log into your instance again with it's new ip address 18.190.3.215 as the original ip address will not longer work.
WeBWorK Configuration
The WeBWorK URL
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.
For this we can use your servers public ip address which we just changed from 18.216.251.98 to 18.190.3.215 or public URL address (e.g. ec2-18.190.3.215.us-east-2.compute.amazonaws.com) but besides being hard to remember this is really not a good idea for the following reason. At least some certificate authorities (e.g. Let's Encrypt) will not issue SLL certificates to sites with a ...compute.amazonaws.com URL because you may release it up and it may be reassigned to another user.
It is much better to use a permanent URL (something like webwork.yourschool.edu) and create a DNS record pointing your URL (webwork.yourschool.edu) to the permanent public ip address of your instance (18.190.3.215 in our example).
If for whatever reason you do not want to use a university URL, you can use Squarespace Domains (https://domains.squarespace.com/) or a similar provider to get and manage your own URL.
The WeBWorK .conf files
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.distwill 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.confThis is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version,localOverrides.conf.distwill be.
It is important to remember that any time you edit WeBWorK's configuration files, you have the restart the webwork2 app for the changes to take effect.
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
$ su wwadmin Password: wwadmin $ cd /opt/webwork/webwork2/conf $ cp site.conf site.conf.bak1 $ nano site.conf
The $server_root_url is set as
$server_root_url = 'http://3.17.9.3/';
which you should replace with
$server_root_url = 'http://18.190.3.215/';
where of course replace 18.190.3.215 by your actual ip address.
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 you might want to hold off on this until you check that your server is functioning well.
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. 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.
If you do not use your school's SMTP server, the following documentation may be helpful:
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html
Or if you want to install your own SMTP server:
https://documentation.ubuntu.com/server/how-to/mail-services/install-postfix/
Then save the file and Quit.
Now restart the webwork2 app so that our changes to the conf files takes effect. First we have to stop acting as wwadmin and return to the ubuntu user.
$ exit exit $ 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.
Test that Things are Working Properly
Connect to http://webwork.yourschool.edu/webwork2 (or http://18.190.3.215/webwork2 if your haven't set up a URL yet) where of course you should use your actual URL or ip address. It may take a few seconds to connect the first time.
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.
Set up WeBWorK to use SSL
This step configures the system so that access to WeBWorK will be through an encrypted connection (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. Note that TLS is the successor protocol to SSL and is used everywhere. So that when we and others use the more common acronym SSL, we really are talking about TLS.
You can find general directions in Set up SSL in the Installation Manual for 2.19 on Ubuntu. In those directions, you want to follow Option1 (Set up Hypnotoad to use SSL (Option 1)) since that is how the AMI was configured.
Here we will give explicit directions for working with your AWS instance, Squarespace Domains and Let's Encrypt. Working with other setups should be analogous.
First we set up our URL
Login to https://domains.squarespace.com/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", select "DNS", under "Custom records" select "ADD RECORD". For "Host" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, and under "DATA" enter 18.190.3.215 where of course you need to enter the permanent ip address you obtained above in Give your Instance a permanent IP address. The click "Save"
Note that it may take a few minutes for your new URL to propagate through the system, so you might have to wait a bit for the next step but in my experience I was able to proceed immediately.
Next we create our SLL certificate and key
First install certbot
$ sudo snap install --classic certbot
Next we need to stop the webwork2 app so that certbot can use port 80
$ sudo systemctl stop webwork2
Now run certbot
$ sudo certbot certonly --standalone
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or space separated) (Enter 'c' to cancel):", I entered "webwork.apizer.org" but of course you want to enter the URL you just setup above. When the process completes, copy the location of your certificate and key, in my case:
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem
Finally make sure that these files are readable by the webwork2 app:
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem
Note that for files to be readable by www-data, www-data must have executable permission on all directories lying above the actual file location. In our case the actual files lie under
/etc/letsencrypt/archive/
since the files under .../live/ are links pointing to files under .../archive/
I have done this twice and in one case certbot created directories that are all world executable, e.g.
ls -l /etc/letsencrypt/ drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive drwxr-xr-x 4 root root 4096 Aug 30 18:59 live
so there was no problem but in the other case there was a problem e.g
ls -l /etc/letsencrypt/ drwx------ 3 root root 4096 Oct 22 17:29 archive/ drwx------ 3 root root 4096 Oct 22 17:29 live/
so I had to run
cd /etc/letsencrypt/ sudo chmod 755 *
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.
Now we we configure the webwork2 app to use SSL
Edit webwork2.mojolicious.yml
We need to tell hypnotoad where the certificates are. First we make a backup of the webwork2.mojolicious.yml file and then edit it:
$ su wwadmin $ cd /opt/webwork/webwork2/conf/ $ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1 $ nano webwork2.mojolicious.yml
In the hypnotoad: section below the lines
listen: - http://*:80
add the line (keeping the indentation)
- https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem
where of course use the path to your certificate and key.
Finally a few lines above this change
redirect_http_to_https: 0
to
redirect_http_to_https: 1
Then save the file and quit.
Edit site.conf
Now backup and then edit site.conf
cp site.conf site.conf.bak2 nano site.conf
The $server_root_url is set as
$server_root_url = 'http://18.190.3.215/';
where of course 18.190.3.215 is replaced by your actual ip address. Change this to
$server_root_url = 'https://webwork.apizer.org/';
where of course use your own URL obtained above and don't forget to enter https in place of http.
The save the file and quit.
Start the webwork2 app
Stop acting as wwadmin and then start the webwork2 app:
$ exit $ sudo systemctl start webwork2
Test that all is well
Try accessing your server using your new URL. E.g. accessing your server using either "http://webwork.apizer.org/webwork2" or "https://webwork.apizer.org/webwork2" (where of course substitute your own URL) should give you a secure connection (most browsers will display a lock symbol) . Check that problems display correctly, the Library Browser behaves well, etc.
Renewing the certificate
Since under our setup the webwork2 app is listening to both ports 80 and 443 and certbot needs to use port 80 for renewals, we must stop the webwork2 app before renewing. Run
$ sudo systemctl stop webwork2 $ sudo certbot renew $ sudo systemctl start webwork2
Note that if you just want to test the renewal process without actually renewing, run
$ sudo certbot renew --dry-run
instead. If you run into problems the first thing to check is permissions, see above.
If you want to use certbot's automatic renewal process
There are two options. The easiest is option2. The best is probably option1.
Option1
Edit webwork2.mojolicious.yml (as user wwadmin in the /opt/webwork/webwork2/conf directory) and at the top of the "hypnotoad:" section under "listen:" make sure you have the line
- http://*:80
in addition to the https: line. A few lines above this change
enable_certbot_webroot_routes: 0
to
enable_certbot_webroot_routes: 1
and above that make sure the "redirect_http_to_https: line reads
redirect_http_to_https: 1
Then save the file and restart the webwork2 app
$ exit $ sudo systemctl restart webwork2
and run the command
$ sudo certbot certonly --webroot -w /opt/webwork/webwork2/tmp \ -d webwork.apizer.org \ --post-hook "chown -R www-data:www-data /etc/letsencrypt && systemctl reload webwork2"
where obviously you need to replace "webwork.apizer.org" with the URL listed on your certificate.
Now test this with
$ sudo certbot renew --dry-run
Option2
Edit webwork2.mojolicious.yml (as user wwadmin) and comment out the line
- http://*:80
so it reads
# - http://*:80
and a few lines above this change
redirect_http_to_https: 1
to
redirect_http_to_https: 0
Then save the file and restart the webwork2 app
$ exit $ sudo systemctl restart webwork2
Now test this with
$ sudo certbot renew --dry-run
Note that this may mean students will need to use https: to connect to your server but many (most?) browsers now default to https: so this is the easiest method.
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.
Passwords
It is IMPERATIVE that you CHANGE THE PASSWORD for the OS user wwadmin (who has access to all WeBWorK files and data). Otherwise anyone can connect to your server and pretty easily gain 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 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
$su wwadmin Password: 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 $exit exit $
Do not forget the <new wwadmin password> that you just entered. Below when we refer to <wwadmin password>, we mean the new <wwadmin password>, <new wwadmin password> that you just entered above.
Change the password for webworkWrite
Now we change the passwords for the MariaDB user webworkWrite. First we edit site.conf.
$su wwadmin Password: <wwadmin password> $ 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 (you do need single or double quotes). We refer to this password as <database_password>. Remember it as we will need it shortly. Then save the file and Quit.
Then restart the webwork2 app so the changes take effect.
$ exit exit $ sudo systemctl restart webwork2
and start MariaDB
$ sudo mysql
You should see
Welcome to the MariaDB monitor ... MariaDBl>
Now lets check the MariaDB users.
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;
You will see a table with four users.
You should see that the user webworkWrite) has 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 user,password,authentication_string,plugin,host 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 ... MariaDBl>
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://webwork.yourschool.edu/webwork2/admin http://webwork.yourschool.edu/webwork2/mytestcourse
where of course you should use your actual URL.
Institution Logo
The institution logo (which is the MAA logo by default) appears on every WeBWorK page. You can replace with you own logo by doing the following. We took these directions verbatim from Alex Jordan's Forum post https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5642.
All you need to do is add lines like these to a config file like localOverrides.conf:
$institutionLogo = 'myimage'; $institutionURL = 'URL for target if a user clicks on the image'; $institutionName = 'Name of the target, to be used in alt text';
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.
The easiest way to do this is to search for the lines
# The institution logo should be an image file in the theme's images folder #$institutionLogo = 'my_school_logo.png'; #$institutionURL = 'http://www.myschool.edu'; #$institutionName = 'My University';
in /opt/webwork/webwork2/conf/localOverrides.conf, remove the #'s from the last three lines and enter your information.
If you want to just make the change for an individual course, copy the code and put it in
/opt/webwork/courses/Course_Name/course.conf.
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.19 on Ubuntu 24.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.19 on Ubuntu 24.04 Server
Changing the instance type
For general information look at the following reference and also google "change the instance type of ec2"
Important: When you stop you instance (as you have to do to change the instance type), your root volume /dev/root (/dev/xvda1) will be saved and this contains all changes you or your students may have made.
First you should review information on ec2 instance types can be found at https://aws.amazon.com/ec2/instance-types/. I would suggest you look at t2 or t3 Instances.
Sign in to the AWS Management Console (https://signin.aws.amazon.com/) and search for the "EC2" service. You will be taken to the Amazon EC2 console.
- In the navigation pane, choose Instances.
- Select the instance and choose Actions, Instance State, Stop.
- In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.
- With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.
- In the Change Instance Type dialog box, do the following:
- From Instance Type, select the instance type that you want.
- (Optional) If the instance type that you selected supports EBS–optimization, select EBS-optimized to enable EBS–optimization or deselect EBS-optimized to disable EBS–optimization. If the instance type that you selected is EBS–optimized by default, EBS-optimized is selected and you can't deselect it.
- Choose Apply to accept the new settings.
- To restart the stopped instance, select the instance and choose Actions, Instance State, Start.
Remember to Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits.
Increase disk space
This is a two part process. The first step is
Expand the EBS root volume
For general information look at the following reference and also google "expand disk of ec2"
Sign in to the AWS Management Console (https://signin.aws.amazon.com/) and search for the "EC2" service. You will be taken to the Amazon EC2 console. In the navigation pane (to the left), choose "Volumes", right click on the volume you what to expand and select "Modify Volume". In the pop up window select the new size, say 25, and click "Modify" and then confirm by clicking "Yes". You will see
Modify Volume Request Succeeded Your volume is now being modified.
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 25GB although in practice you will probably want to make it larger. First enter
$ df -h Filesystem Size Used Avail Use% Mounted on /dev/root 20G 5.3G 15G 28% / ...
to see how much disk space we have initially. Now run parted as root:
$ sudo parted
and you will see something like
GNU Parted 3.3 Using /dev/xvda Welcome to GNU Parted! Type 'help' to view a list of commands. (parted)
Now enter the "print" command
(parted) print Model: Xen Virtual Block Device (xvd) Disk /dev/xvda: 26.8GB Sector size (logical/physical): 512B/512B Partition Table: msdos Disk Flags: Number Start End Size Type File system Flags 1 1049kB 21.5GB 21.5GB primary ext4 boot (parted)
We need to know the number of the partition we want to resize. We can see it is 1 from the above. Now enter the "resizepart" command
(parted) resizepart Partition number? 1 Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue? Yes/No? Yes End? [21.5GB]? 26.5GB (parted)
Now enter the "print" command again
(parted) print Model: Xen Virtual Block Device (xvd) Disk /dev/xvda: 26.8GB Sector size (logical/physical): 512B/512B Partition Table: msdos Disk Flags: Number Start End Size Type File system Flags 1 1049kB 26.5GB 26.5GB primary ext4 boot (parted)
Notice we now have a 26.5 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 1 on /dev/xvda, so we use /dev/xvda1 in the command below
$ sudo resize2fs /dev/xvda1 resize2fs 1.45.5 (07-Jan-2020) Filesystem at /dev/xvda1 is mounted on /; on-line resizing required old_desc_blocks = 3, new_desc_blocks = 4 The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.
and run df -h and we should see something like
$ df -h Filesystem Size Used Avail Use% Mounted on /dev/root 24G 5.3G 19G 23% / ...
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.19_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.
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. 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.
-- Main.ArnoldPizer - August 2024
