Difference between revisions of "WeBWorK 2.15 Ubuntu Server 20.04 LTS Amazon Machine Image"

From WeBWorK_wiki
Jump to navigation Jump to search
 
(39 intermediate revisions by the same user not shown)
Line 21: Line 21:
   
 
===Find the AMI image===
 
===Find the AMI image===
Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/ . 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), choose AMIs. Then select "Public images" and in the search bar enter "WeBWorK". You should see <code>WeBWorK 2.15 on Ubuntu Server 20.04 LTS</code> listed.
+
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. 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 <code>WeBWorK 2.15 on Ubuntu Server 20.04 LTS</code> listed.
   
 
===Configure the WeBWorK AMI Image ===
 
===Configure the WeBWorK AMI Image ===
Line 29: Line 29:
 
====Choose an Instance Type====
 
====Choose an Instance Type====
   
Information on ec2 instance types can be found at https://aws.amazon.com/ec2/instance-types/
+
Information on ec2 instance types can be found at https://aws.amazon.com/ec2/instance-types/. I would suggest you look at t2 Instances.
   
 
The WeBWorK AMI was built from a t2.micro ec2 instance (which is free tier eligible) having the following resources:
 
The WeBWorK AMI was built from a t2.micro ec2 instance (which is free tier eligible) having the following resources:
Line 44: Line 44:
 
The MAA courses1 server is hosting over 600 courses of which around 150 were active in June, 2020.
 
The MAA courses1 server is hosting over 600 courses of which around 150 were active in June, 2020.
   
Most likely the resources required for you server will fall within the range from t2.micro to t2.2xlarge. You can always change the resources available to an instance but for this you will have to stop the instance. After restarting the instance will have a new ip address which means you will have to change the network setup (see [[#The WeBWorK URL|The WeBWorK URL]] below). For this reason it is best to start will reasonable resources.
+
Most likely the resources required for you server will fall within the range from t2.micro to t2.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. After restarting the instance will have a new ip address which means you will have to change the network setup (see [[#The WeBWorK URL|The WeBWorK URL]] below). For this reason it is best to start will reasonable resources. For a server that you will be using with students it might be reasonable to start with a t2.small or t2.medium instance. But of course this is highly dependent on the number of students who will be using the server simultaneously.
   
 
====Configure Instance Details====
 
====Configure Instance Details====
 
  +
You probably will want to use the default settings.
   
 
====Add Storage====
 
====Add Storage====
   
You can change the amount of disk space
+
You can change the amount of disk space but 20 GB is a reasonable amount to start with for a small server.
   
 
Also make sure that Delete on Termination is unchecked. Otherwise when you stop you instance, your root volume /dev/root (/dev/xvda1) will be deleted and this contains all changes you or your students may have made. Note that rebooting your server does not do this but stopping it (e.g. to increase memory or other resources) will.
 
Also make sure that Delete on Termination is unchecked. Otherwise when you stop you instance, your root volume /dev/root (/dev/xvda1) will be deleted and this contains all changes you or your students may have made. Note that rebooting your server does not do this but stopping it (e.g. to increase memory or other resources) will.
Line 58: Line 58:
 
Read about Tags and add some if you want (e.g. name the instance)
 
Read about Tags and add some if you want (e.g. name the instance)
 
====Configure Security Group====
 
====Configure Security Group====
You can use the default security group or create a new one. You also should create inbound rules so that you and others can communicate with your server instance.
+
You can use the default security group or create a new one.
SSH is already set up but the source <code>0.0.0.0/0</code> means, as the warring states: "Rules with source of 0.0.0.0/0 allow all IP addresses to access your instance." 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).
+
  +
You also should create inbound rules so that you and others can communicate with your server instance.
  +
SSH is already set up but the source <code>0.0.0.0/0</code> means, as the warring states: "Rules with source of 0.0.0.0/0 allow all IP addresses to access your instance." 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). Under "Source" 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
 
SSH TCP 22 98.12.176.149/32 SSH for admin
   
You should also allow HTTP (port 80) and Lighttpd (port 8080). Initially for testing you may want to restrict these but for a production machine you would want to allow access from anywhere, i.e. <code>0.0.0.0/0</code>. Note that except for guest users (who have very limited access), no one can log into WeBWorK on your server without a password. But see the section [[#Passwords|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.
+
You should also allow HTTP (port 80) and Lighttpd (port 8080). Initially for testing you may want to restrict these but for a production machine you would want to allow access from anywhere, i.e. <code>0.0.0.0/0</code>. Note that except for guest users (who have very limited access), no one can log into WeBWorK on your server without a password. But see the section [[#Passwords|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed. Now click "Add Rule" to add the following two rules
   
HTTP TCP 80 0.0.0.0/0 HPPP
+
HTTP TCP 80 0.0.0.0/0 HTTP
 
Custom TCP TCP 8080 0.0.0.0/0 Lighttpd
 
Custom TCP TCP 8080 0.0.0.0/0 Lighttpd
  +
  +
====Review and Launch====
  +
Click "Review and Launch" to review your instance.
   
 
==Launch Your Server==
 
==Launch Your Server==
   
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).
+
Click "Launch". Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem). And acknowledge that you have access to the private key file (e.g. WWsecretkey.pem).
   
Now Launch you server.
 
  +
Now Launch you server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard.
   
On you EC2 Dashboard (EC2 Management Console), find the IPv4 Public IP address, say 18.230.220.181. Will use this in our examples. Obviously you should substitute your own.
+
On you EC2 Dashboard (EC2 Management Console), find the IPv4 Public IP address, say 18.230.220.181. We will use this in our examples. Obviously you should substitute your own.
   
 
=== Accessing Your Server from a Terminal Emulator on your Host ===
 
=== Accessing Your Server from a Terminal Emulator on your Host ===
Line 230: Line 233:
 
But we are not supposed to edit the <code>defaults.config</code> file, so if we want to do this, we will copy this to <code>localOverrides.conf</code> and edit it appropriately. Note that we should move this setting to the <code>site.conf</code> file.
 
But we are not supposed to edit the <code>defaults.config</code> file, so if we want to do this, we will copy this to <code>localOverrides.conf</code> and edit it appropriately. Note that we should move this setting to the <code>site.conf</code> file.
   
==== Edit the localOverrides.conf file ====
+
====Edit the localOverrides.conf file====
 
Now backup and edit localOverrides.conf (we already have two backups)
 
Now backup and edit localOverrides.conf (we already have two backups)
 
$ cd /opt/webwork/webwork2/conf
 
$ cd /opt/webwork/webwork2/conf
Line 240: Line 243:
 
^ \
 
^ \
 
Search (to replace) [...]:aws.apizer.org
 
Search (to replace) [...]:aws.apizer.org
Replace with:webwork.youryourschool.edu
+
Replace with:webwork.yourschool.edu
 
A
 
A
 
where of course replace <code>webwork.yourschool.edu</code> by your actual URL.
 
where of course replace <code>webwork.yourschool.edu</code> by your actual URL.
Line 286: Line 289:
 
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 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 that 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.
+
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==
 
==Set up WeBWorK to use SSL==
Line 444: Line 447:
 
$ cd /etc/apache2/sites-available
 
$ cd /etc/apache2/sites-available
 
$ sudo cp 000-default.conf 000-default.conf.bak1
 
$ sudo cp 000-default.conf 000-default.conf.bak1
[sudo] password for wwadmin: <wwadmin password>
 
 
$ sudo nano 000-default.conf
 
$ sudo nano 000-default.conf
   
Line 459: Line 461:
 
and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.edu/webwork2/.
 
and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.edu/webwork2/.
   
  +
===Trouble with SSL certificates===
  +
  +
If you are trying to use untrusted SSL certificates (e.g. self signed certificates) people may experience trouble with certain browsers (e.g. Chrome) even if they initially accept the insecure certificate and are able to log into their course. A symptom of this is that mathematical expressions will not be visible in MathJax mode. A workaround is to disable lighttpd. To do this copy the five lines of code from the section
  +
[[Installation_Manual_for_2.15_on_Ubuntu_20.04_Server#Disabling_Optional_B_.28lighttpd.29_for_a_single_course]]
  +
and paste it into the localOverrides.conf file just above the last line on the file
  +
1; #final line of the file to reassure perl that it was read properly.
  +
To do this
  +
$ su wwadmin
  +
Password: wwadmin
  +
$ cd /opt/webwork/webwork2/conf
  +
$ nano localOverrides.conf
  +
and paste the five lines from the above section maybe changing the comment to "Do not use lightppd (port 8080) for this server". Then save the file and quit and return to being the ubuntu user. This is a quick and dirty fix. You could instead edit the individual lines in the body of the localOverrides.conf file. This fix also puts an additional strain on your server since displaying mathematical expressions, images, etc calls up an Apache2 process rather than a lightweight lighttpd process. The best solution is to obtain an official trusted SSL certificate and install it properly both for apache2 and lighttpd.
   
 
==Finish up==
 
==Finish up==
Line 529: Line 543:
 
If you want to check that you set the password correctly, do the following:
 
If you want to check that you set the password correctly, do the following:
 
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp
 
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp
Enter password: <code>&lt;database_password&gt;</code>
+
Enter password: <database_password>
 
and you should see
 
and you should see
 
Welcome to the MySQL monitor ...
 
Welcome to the MySQL monitor ...
Line 571: Line 585:
   
 
For general information look at the following reference and also google "change the instance type of ec2"
 
For general information look at the following reference and also google "change the instance type of ec2"
* https://aws.amazon.com/premiumsupport/knowledge-center/resize-instance/
+
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance
   
 
'''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. This is because when your instance was created "Delete on Termination" was unchecked ('''unless you explicitly changed that'''). Otherwise when you stop you instance, your root volume /dev/sda1 will be deleted. If necessary you can change this setting for a running instance.
 
'''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. This is because when your instance was created "Delete on Termination" was unchecked ('''unless you explicitly changed that'''). Otherwise when you stop you instance, your root volume /dev/sda1 will be deleted. If necessary you can change this setting for a running instance.
  +
  +
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 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.
  +
  +
After your instance starts, find its '''new''' public ip address and redirect your fixed URL (<code>webwork.yourschool.edu</code> in our example above) to the new ip address. If you do not have a fixed URL, you will have to [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]]. Look at [[#The WeBWorK URL|The WeBWorK URL]] for an explanation. Also remember to [[#Adjust Apache's configuration according to your server's memory]].
   
 
===Increase disk space===
 
===Increase disk space===
Line 582: Line 612:
 
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/
 
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/
   
Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/ . In the navigation pane (to the left), choose "Volumes", right click
+
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".
 
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
 
You will see
Line 736: Line 766:
 
-- Main.ArnoldPizer - 10 May 2020 <br />
 
-- Main.ArnoldPizer - 10 May 2020 <br />
   
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Virtual Machine Images]]
+
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]

Latest revision as of 17:28, 13 August 2020


These instructions cover setting up WeBWorK 2.15 using the WeBWorK 2.15 Ubuntu Server 20.04 LTS Amazon Machine Image.

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

Contents

Setting up the WeBWorK 2.15 Ubuntu Server 20.04 LTS Amazon Machine Image[edit]

Overview[edit]

After using the WeBWorK 2.15 Ubuntu Server 20.04 LTS Amazon Machine Image, you will have a full fledged Ubuntu Server 20.04 LTS system with WeBWorK 2.15, Apache2, MySQL, R server, lighttpd, 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 MySQL user webworkWrite who has access to MySQL, for the WeBWorK user admin who has admin privileges and for the WeBWorK user profa who has professor privileges (see below). Finally you should set up SSL (https) access to WeBWorK if students will be using your server.

There are more detailed instructions for Ubuntu Server 20.04 and WeBWorK 2.15 at Installation Manual for 2.15 on Ubuntu 20.04 Server. The AMI (Amazon Machine Image) was built following those instructions.

First you need an AWS account[edit]

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[edit]

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. 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.15 on Ubuntu Server 20.04 LTS listed.

Configure the WeBWorK AMI Image[edit]

Select the WeBWorK 2.15 on Ubuntu Server 20.04 LTS AMI and hit Launch

Choose an Instance Type[edit]

Information on ec2 instance types can be found at https://aws.amazon.com/ec2/instance-types/. I would suggest you look at t2 Instances.

The WeBWorK AMI was built from a t2.micro ec2 instance (which is free tier eligible) having the following resources:

  • 20 GB disk drive of which about 6 GB is used
  • 1 GB memory
  • 1 (virtual) cpu

The above resources are very minimal. These resources are OK for testing but it is easy to overwhelm the machine even with a single user. This may happen e.g. if you want to simultaneously display many problems in the Library Browser. If this happens your options are to wait until the server recovers or reboot the server.

The Mathematical Association of America (MAA) courses1 server (https://courses1.webwork.maa.org/webwork2) is a t2.2xlarge ec2 instance having the following resources:

  • 70 GB disk drive
  • 32 GB memory
  • 8 (virtual) cpu's

The MAA courses1 server is hosting over 600 courses of which around 150 were active in June, 2020.

Most likely the resources required for you server will fall within the range from t2.micro to t2.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. After restarting the instance will have a new ip address which means you will have to change the network setup (see The WeBWorK URL below). For this reason it is best to start will reasonable resources. For a server that you will be using with students it might be reasonable to start with a t2.small or t2.medium instance. But of course this is highly dependent on the number of students who will be using the server simultaneously.

Configure Instance Details[edit]

You probably will want to use the default settings.

Add Storage[edit]

You can change the amount of disk space but 20 GB is a reasonable amount to start with for a small server.

Also make sure that Delete on Termination is unchecked. Otherwise when you stop you instance, your root volume /dev/root (/dev/xvda1) will be deleted and this contains all changes you or your students may have made. Note that rebooting your server does not do this but stopping it (e.g. to increase memory or other resources) will.

Add Tags[edit]

Read about Tags and add some if you want (e.g. name the instance)

Configure Security Group[edit]

You can use the default security group or create a new one.

You also should create inbound rules so that you and others can communicate with your server instance. SSH is already set up but the source 0.0.0.0/0 means, as the warring states: "Rules with source of 0.0.0.0/0 allow all IP addresses to access your instance." 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). Under "Source" 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 also allow HTTP (port 80) and Lighttpd (port 8080). 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), 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. Now click "Add Rule" to add the following two rules

HTTP	            TCP	            80	           0.0.0.0/0	               HTTP
Custom TCP	    TCP	            8080	   0.0.0.0/0                   Lighttpd

Review and Launch[edit]

Click "Review and Launch" to review your instance.

Launch Your Server[edit]

Click "Launch". Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem). And acknowledge that you have access to the private key file (e.g. WWsecretkey.pem).

Now Launch you server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard.

On you EC2 Dashboard (EC2 Management Console), find the IPv4 Public IP address, say 18.230.220.181. We will use this in our examples. Obviously you should substitute your own.

Accessing Your Server from a Terminal Emulator on your Host[edit]

You can login to your server using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program.

If you use a terminal emulator like MobaXterm use the Advanced SSH Settings to use the WWsecretkey.pem file as your private key and connect to 18.230.220.181 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.230.220.181

(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.230.220.181

Users on your system[edit]

There are two users who can login to the system: ubuntu and wwadmin

ubuntu[edit]

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[edit]

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 #. To do this run

$ sudo su
#

When you want to exit the root prompt and return to being the regular user ubuntu, do the following

# exit
exit
$

wwadmin[edit]

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[edit]

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

$ timedatectl

and you will see (in the summer)

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

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

$  timedatectl list-timezones

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

$ sudo timedatectl set-timezone America/Los_Angeles

and then

$ timedatectl

to check it was set correctly.

Checking for and installing WeBWorK hotfixes[edit]

Follow the instructions at Checking for and Installing Hotfixes in the Installation Manual for 2.15 on Ubuntu 20.04 Server.

WeBWorK Configuration[edit]

The WeBWorK URL[edit]

We need a WeBWorK URL both to

  1. configure WeBWorK by editing the localOverrides.conf file
  2. to give to students and professors so that they can access WeBWorK

For this we can use your servers public ip address (e.g. 18.230.220.181) or public URL address (e.g. ec2-18.230.220.181.us-east-2.compute.amazonaws.com) but besides being hard to remember this is really not a good idea for the following reason. These public addresses are only "semi-permanent". As long as your server instance is running they will remain fixed and will also remain fixed if you reboot your instance. However, if you stop your instance for any reason (e.g. to increase the resources it has) the public addresses will disappear and when you restart your server, it will have new and different public addresses. Then you will have to edit the localOverrides.conf file and tell all your users they need to use a new URL to access WeBWorK.

It is much better to use a permanent URL (something like webwork.yourschool.edu) and direct that to the public ip address of your instance (18.230.220.181 in our example). Then if your ever have to stop and restart your AWS instance, all you have to do is to redirect the webwork.yourschool.edu URL to the new public ip address. In my experience such changes propagate through the name servers in minutes.

If for whatever reason you do not want to use a university URL, you can use Google Domains (https://domains.google/) or a similar provider to get and manage your own URL.

The WeBWorK .conf files[edit]

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.

It is important to remember that any time you edit WeBWorK's configuration files, you have the restart Apache2 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[edit]

Now backup and edit site.conf

$ su wwadmin
Password: wwadmin
$ cd /opt/webwork/webwork2/conf
$ cp site.conf site.conf.bak1


The $server_root_url is set as

 $server_root_url   = 'http://localhost';

which should be fine.

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.

Now edit site.conf

$ nano site.conf

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 three instances. The PG system sends mail to report answers to questionnaires and free-response problems. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.

To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. 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://ubuntu.com/server/docs/mail-postfix

Then save the file and Quit.

The defaults.config file[edit]

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

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

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

Edit the localOverrides.conf file[edit]

Now backup and edit localOverrides.conf (we already have two backups)

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

We have to replace all occurrences of aws.apizer.org by your the new URL (webwork.yourschool.edu in our example above). You can do this one by one or by a global search and replace. To use global search and replace enter the command:

^ \
Search (to replace) [...]:aws.apizer.org
Replace with:webwork.yourschool.edu
A

where of course replace webwork.yourschool.edu by your actual URL.

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

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

Of course you have to remove the comment character #.

Then save the file and Quit.

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

$ sudo apache2ctl restart

Test that Things are Working Properly[edit]

Connect to http://webwork.yourschool.edu/webwork2 where of course you should use your actual URL. We will test out a few important parts of WeBWorK. If you run into problems, you should look at the Apache error log which is located at /var/log/apache2/error.log. And you should look at Test that Things are Working Properly in the Installation Manual for 2.15 on Ubuntu 20.04 Server 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". At this point you are a regular professor. There is also an administrator "admin", a regular student "jsmith" and several guest or practice users (who don't require a password but can view problems and "check" answers without them being "submitted" for credit). More on these below.

Now click on Homework Sets on the Main Menu and click on Demo. Then look at the problems. Mathematical equations should be typeset. 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 PDF .... The page is a little complicated because you are a professor so you see the professor view (students see a very simple page) but you can just scroll to the bottom and click on Generate hardcopy for selected users and selected sets.

Look through the problems in the other sets.

Now test the Library Browser. Note when using the Library Browser the default is to view 20 problems at once. If you are using the t2.micro ec2 instance level, this may overwhelm the server. You can display fewer problems and e.g. use the "top" command to check the load on the server.

If "top" shows a high load average and/or shows the kswapd0 process taking a large percentage of cpu then your system is getting overwhelmed. In particular kswapd0 manages virtual memory and may be having issues due to moving processes to SWAP too frequently, causing cpu spikes and decreased system performance. The solution is to allocate more memory to your instance. If your server gets hopelessly bogged down, you can try to wait it out or just reboot.

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[edit]

This step configures apache 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. The non encrypted lighttpd server is being used for images, MathJax, etc. so we might have to set up the lighttpd server to run under SSL (see below).

First we have to obtain an official SSL certificate or generate a self-signed one which can be used for testing purposes. If students will be using your server, it is better to obtain an official SSL certificate since using a self-signed certificate with cause warning messages to be displayed when students connect to the server.

Obtain an Official SSL Certificate[edit]

Talk to the networking group on your campus about obtaining an official certificate. You can find information on the net about certificate providers, e.g. http://www.sslshopper.com/certificate-authority-reviews.html .

The certificate goes in /etc/ssl/certs/ and the key file goes in /etc/ssl/private/.

Use a self-signed Certificate[edit]

When we installed the package openssh-server a self-signed certificate was automatically created. The certificate is stored at

/etc/ssl/certs/ssl-cert-snakeoil.pem

and the private key at

/etc/ssl/private/ssl-cert-snakeoil.key

This certificate and key may be regenerated manually with the following command (needs root privileges i.e. sudo):

$ sudo make-ssl-cert generate-default-snakeoil --force-overwrite

which you might want to do since I believe the original certificate is only valid for 365 days.

In the instructions below we will use the provided self-signed certificate (ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key) but you can also generate your own using openssh following instructions on the web. As we said above, for a production server, you should really use an official certificate.

Add inbound rules for Apache and Lighttpd[edit]

Create inbound rules for Apache on port 443 and for Lighttpd on port 8443. On your EC2 Management console, select the "Security Group" for your instance, the "Inbound Rules" and "Edit" and then "add" the rules

HTTPS	            TCP	         443	        0.0.0.0/0	         HTTPS
Custom TCP	    TCP	        8443	        0.0.0.0/0	      Lighttpd SSL

Initially for testing you may want to restrict these but for a production machine you would want to allow from anywhere, i.e. 0.0.0.0/0

Set up Apache to use SSL[edit]

First we enable the mod_ssl module

$ sudo a2enmod ssl

Now we have to configure Apache to use SSL.

$ cd /etc/apache2/sites-available/
$ sudo cp default-ssl.conf default-ssl.conf.bak1
$ sudo nano default-ssl.conf

Our self-signed certificate and key files are named ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key. If you are using official files, put their names in the lines below. You will also have to edit the Certificate Chain, Certificate Authority and possibly other items. Instructions for doing so are beyond the scope of this document. You might look at https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-ubuntu-18-04

Search for the lines

SSLCertificateFile      /etc/ssl/certs/ssl-cert-snakeoil.pem
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key

and replace ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key by the names of your certificate. Since in these instructions we are using ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key, we can just leave the lines as is.

Then save the file and quit. And enable default-ssl.conf

$ sudo a2ensite default-ssl.conf

Finally we restart Apache

$ sudo systemctl restart apache2

Edit site.conf[edit]

This is important. We have to edit the value of $server_root_url in webwork2/conf/site.conf so that it uses https (so it should read e.g. 'https://localhost'). If you don't do this, your may run into strange problems in the Library Browser. To check, open the Library Browser, select a subject and then click on the chapter area. If you see a drop down list of chapters, things are working properly.

Now we edit site.conf

$ su wwadmin
Password: wwadmin
$ cd /opt/webwork/webwork2/conf
$ cp site.conf site.conf.bak1
$ nano site.conf

In the line

$server_root_url = 'http://localhost';

replace http by https. Then save the file, quit, return to being the ubuntu user and restart apache

$ exit
exit
$ sudo service apache2 restart

Configure lighttpd to use SSL[edit]

We are using lighttpd for images, pdf's, MathJax, etc. MathJax will fail (so mathematical expressions will not be displayed) if you do not configure lighttpd to use SSL. So let's configure lighttpd to use SSL.

For lighttpd you need to concatenate the key file and the certificate file into a single pem file by running the following command. Obviously you should use the real name of your certificate and key files, not "apache.key" and "apache.crt".

$ sudo su
# cd /etc/ssl/private
# cat apache.key ../certs/apache.crt > apache.pem
# chmod 640 apache.pem
# exit
$

If you are using official certificates, you will also have to edit the Certificate Chain, Certificate Authority and possibly other items. Instructions for doing so are beyond the scope of this document. See e.g. http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_SSL and/ or https://www.vultr.com/docs/setup-let-s-encrypt-with-lighttpd-on-ubuntu-16-04


Since we already are using the files ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key for apache, we will also use them for lighttpd

$ sudo cat /etc/ssl/private/ssl-cert-snakeoil.key /etc/ssl/certs/ssl-cert-snakeoil.pem >/etc/lighttpd/lighttpd.pem

Now edit lighttpd.conf.

$ cd /etc/lighttpd
$ sudo cp lighttpd.conf lighttpd.conf.bak2
$ sudo nano lighttpd.conf

First in the list of server.modules at the top of the file, under the last module "mod_setenv",, add the module

"mod_openssl",

Next under the line

server.port                 = 8080

add the following

$SERVER["socket"] == ":8443" {
  ssl.engine = "enable"
  ssl.pemfile = "/etc/lighttpd/lighttpd.pem"
}

Then save the file and quit.

And restart lighttpd and check it's status


$ sudo systemctl restart lighttpd
$ sudo systemctl status lighttpd

Sometimes when Lighttpd would not restart (or start) I just rebooted the server and everything worked. If you have difficulty you can run the command

$ sudo lsof -i -P -n | grep LISTEN

which will list all the ports your server is listening to. In the list you should see something similar to

lighttpd  519        www-data    5u  IPv4  18610      0t0  TCP *:8443 (LISTEN)

Edit localOverrides.conf[edit]

$su wwadmin
Password: wwadmin
$ cd /opt/webwork/webwork2/conf
$ cp localOverrides.conf localOverrides.conf.bak4
$ nano localOverrides.conf

and replace all occurrences of 8080 by 8443 (one occurrence in three different lines). Then in these same three lines replace http by https . Obviously, you have to edit the three active lines and can ignore the commented out lines.

Then save the file and quit, return to being the ubuntu user and restart apache

$exit
exit
$ sudo service apache2 restart
password:<wwadmin password>

and test that all is well by viewing a page with math expressions using MathJax mode.

Test that things are still working properly[edit]

Connect to https://yourserver.yourschool.edu/webwork2/myTestCourse You will be asked to accept the certificate. After you do so things should work just as before except that the connection will be via https except for images, MathJax, etc. if you using lighttpd. In that case, viewing math expressions in image mode should work fine but it is possible using MathJax mode will fail. We will talk about this below.

Redirect http requests to https[edit]

Assuming that everything is working, the last thing we do is set things up so that requests to http://yourserver.yourschool.edu/webwork2/ are automatically redirected to https://yourserver.yourschool.edu/webwork2/.

$ cd /etc/apache2/sites-available
$ sudo cp 000-default.conf 000-default.conf.bak1
$ sudo nano 000-default.conf

In the

<VirtualHost *:80>

section just under the line

DocumentRoot /var/www/html

add the line

Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2

where of course you should edit yourserver.yourschool.edu appropriately. Then save the file and quit. Restart Apache

$ sudo service apache2 restart

and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.edu/webwork2/.

Trouble with SSL certificates[edit]

If you are trying to use untrusted SSL certificates (e.g. self signed certificates) people may experience trouble with certain browsers (e.g. Chrome) even if they initially accept the insecure certificate and are able to log into their course. A symptom of this is that mathematical expressions will not be visible in MathJax mode. A workaround is to disable lighttpd. To do this copy the five lines of code from the section Installation_Manual_for_2.15_on_Ubuntu_20.04_Server#Disabling_Optional_B_.28lighttpd.29_for_a_single_course and paste it into the localOverrides.conf file just above the last line on the file

1; #final line of the file to reassure perl that it was read properly.

To do this

$ su wwadmin
Password: wwadmin
$ cd /opt/webwork/webwork2/conf
$ nano localOverrides.conf

and paste the five lines from the above section maybe changing the comment to "Do not use lightppd (port 8080) for this server". Then save the file and quit and return to being the ubuntu user. This is a quick and dirty fix. You could instead edit the individual lines in the body of the localOverrides.conf file. This fix also puts an additional strain on your server since displaying mathematical expressions, images, etc calls up an Apache2 process rather than a lightweight lighttpd process. The best solution is to obtain an official trusted SSL certificate and install it properly both for apache2 and lighttpd.

Finish up[edit]

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[edit]

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

Change the password for wwadmin[edit]

$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>).

Change the password for webworkWrite[edit]

Now we change the passwords for the MySQL 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. We refer to this password as <database_password>. Remember it as we will need it shortly. Then save the file and Quit.

Then restart Apache so the changes take effect.

$ exit
exit
$ sudo apache2ctl graceful

and start MySQL

$ sudo mysql

You should see

Welcome to the MySQL monitor ...
mysql>

Now lets check the MySQL users.

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

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

Now we will change the password for the webworkWrite User

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

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

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

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

Then exit MySQL

mysql> exit
Bye
$

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

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

and you should see

Welcome to the MySQL monitor ...
mysql>

Now exit

mysql> exit
Bye
$

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

Change the password for admin[edit]

Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (http://.../webwork2/admin) and myTestCourse (http://.../webwork2/myTestCourse) with Username "admin" and Password "admin". Then change the passwords from "admin" to something more secure. Note that in WeBWorK to change the password of the user you are logged in as, select "User Settings" in the "MAIN MENU". Or you can login as "profa" and use the "Classlist Editor" to change the password.

Change the password for profa[edit]

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 "Classlist Editor" to change the password.

Change the password for jsmith[edit]

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 "Classlist Editor" to change the password.

More House Keeping[edit]

Hide the admin and myTestCourse courses[edit]

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.

Adjust Apache's configuration according to your server's memory[edit]

Look at Edit mpm_prefork.conf in the Installation Manual for 2.15 on Ubuntu 20.04 Server and adjust "MaxRequestWorkers" according to the rule of thumb given there.

Set up access to Apache's server-info and servo-status[edit]

This isn't really necessary but you should look at the info.conf and status.conf section in Installation Manual for 2.15 on Ubuntu 20.04 Server.

Changing the instance type[edit]

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. This is because when your instance was created "Delete on Termination" was unchecked (unless you explicitly changed that). Otherwise when you stop you instance, your root volume /dev/sda1 will be deleted. If necessary you can change this setting for a running instance.

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

  1. In the navigation pane, choose Instances.
  2. Select the instance and choose Actions, Instance State, Stop.
  3. In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.
  4. With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.
  5. In the Change Instance Type dialog box, do the following:
  6. From Instance Type, select the instance type that you want.
  7. (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.
  8. Choose Apply to accept the new settings.
  9. To restart the stopped instance, select the instance and choose Actions, Instance State, Start.

After your instance starts, find its new public ip address and redirect your fixed URL (webwork.yourschool.edu in our example above) to the new ip address. If you do not have a fixed URL, you will have to Edit the localOverrides.conf file. Look at The WeBWorK URL for an explanation. Also remember to #Adjust Apache's configuration according to your server's memory.

Increase disk space[edit]

This is a two part process. The first step is

Expand the EBS root volume[edit]

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[edit]

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/sda, so we use /dev/sda2 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!

Checking for and Installing Hotfixes[edit]

The following commands show you how to check for and install bug fixes. Important Note: These commands check and retrieve the master branch which gives the latest stable release of the software package (webwork2, pg, etc.) with bug fixes. If a stable release newer than 2.15 exists for webwork2 and/or pg, that will be checked and retrieved which is probably not what you want. Please check before updating. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/master/VERSION and https://github.com/openwebwork/pg/blob/master/VERSION.

To check if there are bug fixes, do the following.

Updating the webwork2 code[edit]

First we check for updates to the webwork2 code:

cd /opt/webwork/webwork2/
git remote show origin

This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run

git pull origin

and restart apache2.

Updating the pg code[edit]

Now check for updates to the pg code:

cd /opt/webwork/pg/
git remote show origin

This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run

git pull origin

and restart apache2.

Restart apache2[edit]

Important: After updating either webwork2 or pg, you have to restart apache2

$ sudo apache2ctl restart
password:<wwadmin password>

Updating the OPL[edit]

The following assumes you have already installed the OPL. For that see #Install the Open Problem Library below. Now check for updates to the Open Problem Library:

cd /opt/webwork/libraries/webwork-open-problem-library
git remote show origin

This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run

git pull origin

Then rerun the OPL-update script. Updating the OPL is pretty much risk free since changes usually involve only a relatively small number of individual problems and the vast majority of problems remain unchanged. Updating the OPL does not require restarting apache2.

$ OPL-update


File and Directory Locations and System Information[edit]

After launching your WeBWorK instance will be identical to a system created by following the instructions Installation Manual for 2.15 on Ubuntu 20.04 Server with all Optional Configurations A-E implemented except that

  1. Optional A is implemented with the wwtmp directory set up as a separate directory but not as a separate partition
  2. Optional C is not implemented. Optional C configures Apache (and optionally lighttpd) so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally if you are using official certificates.
  3. The Ubuntu Server 20.04 LTS image is from the "Ubuntu 20.04 LTS - Focal" AMI provided by Canonical Group, Ltd. (see https://aws.amazon.com/marketplace). So all system files are in their standard Ubuntu locations.
  4. snapd has been removed (see snapd below)
  5. The PGbasicmacros.pl file has been slightly changed (see PGbasicmacros.pl below)


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

You should read through the instructions Installation Manual for 2.15 on Ubuntu 20.04 Server in order to understand how your server has been set up, find the locations of the WeBWorK system files, see directions for restarting Apache2, MySQL, etc.

Known Issues[edit]

Here are the known issues with this release.

PGbasicmacros.pl[edit]

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 above). For information on this see https://github.com/openwebwork/pg/issues/473.

To fix this the PGbasicmacros.pl file (in the directory /opt/webwork/pg/macros) has been slightly changed. The original file is PGbasicmacros.pl.bak1 in the same directory. This may or may not be addressed in a WeBWorK 15 hotfix (see Checking for and Installing Hotfixes).

UTF-8 support[edit]

WW 2.15 has some "known issues" with the UTF-8 support that arise in some WeBWorK problems. These issues are discussed in a forum discussion at: https://webwork.maa.org/moodle/mod/forum/discuss.php?d=4795. The discussion there lists pull requests by Nathan Wallach and Davide Cervone that address these issues. If you write or use WeBWorK problems that have issues with UTF-8 characters, look at that discussion. Again these issues may or may not be addressed in a WeBWorK 15 hotfix (see Checking for and Installing Hotfixes).

snapd[edit]

In our t2.micro instance, snapd was using a large amount of resources, so we removed it

$ sudo systemctl stop snapd
$ sudo apt purge snapd
$ sudo apt autoremove


-- Main.ArnoldPizer - 10 May 2020