https://webwork.maa.org/mediawiki_new/api.php?action=feedcontributions&user=Apizer&feedformat=atomWeBWorK_wiki - User contributions [en]2024-03-19T09:21:38ZUser contributionsMediaWiki 1.34.0https://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24330WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2024-03-11T17:33:40Z<p>Apizer: /* If you want to use certbot's automatic renewal process */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line (keeping the indentation)<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
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<br />
$ sudo systemctl stop webwork2<br />
$ sudo certbot renew<br />
$ sudo systemctl start webwork2<br />
Note that if you just want to test the renewal process without actually renewing, run<br />
$ sudo certbot renew --dry-run<br />
instead. If you run into problems the first thing to check is permissions, see above.<br />
=====If you want to use certbot's automatic renewal process=====<br />
There are two options. The best is to follow the instructions at https://github.com/openwebwork/webwork2/pull/2321<br />
<br />
The other is to try the following:<br />
<br />
Edit webwork2.mojolicious.yml and comment out the line <br />
- http://*:80<br />
so it reads<br />
# - http://*:80<br />
and a few lines above this change<br />
redirect_http_to_https: 1<br />
to<br />
redirect_http_to_https: 0<br />
and restart the webwork2 app<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
Now test this with<br />
$ sudo certbot renew --dry-run<br />
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 probably the preferred method.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24252WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-23T18:28:53Z<p>Apizer: /* Renewing the certificate */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line (keeping the indentation)<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
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<br />
$ sudo systemctl stop webwork2<br />
$ sudo certbot renew<br />
$ sudo systemctl start webwork2<br />
Note that if you just want to test the renewal process without actually renewing, run<br />
$ sudo certbot renew --dry-run<br />
instead. If you run into problems the first thing to check is permissions, see above.<br />
=====If you want to use certbot's automatic renewal process=====<br />
One option is to edit webwork2.mojolicious.yml and comment out the line <br />
- http://*:80<br />
so it reads<br />
# - http://*:80<br />
and a few lines above this change<br />
redirect_http_to_https: 1<br />
to<br />
redirect_http_to_https: 0<br />
and restart the webwork2 app<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
Now test this with<br />
$ sudo certbot renew --dry-run<br />
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 probably the preferred method.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24251WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-23T16:51:32Z<p>Apizer: /* If you want to use certbot's automatic renewal process */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line (keeping the indentation)<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
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<br />
$ sudo systemctl stop webwork2<br />
$ sudo certbot renew<br />
$ sudo systemctl start webwork2<br />
Note that if you just want to test the renewal process without actually renewing, run<br />
$ sudo certbot renew --dry-run<br />
instead. <br />
=====If you want to use certbot's automatic renewal process=====<br />
One option is to edit webwork2.mojolicious.yml and comment out the line <br />
- http://*:80<br />
so it reads<br />
# - http://*:80<br />
and a few lines above this change<br />
redirect_http_to_https: 1<br />
to<br />
redirect_http_to_https: 0<br />
and restart the webwork2 app<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
Now test this with<br />
$ sudo certbot renew --dry-run<br />
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 probably the preferred method.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24250WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-23T16:49:59Z<p>Apizer: /* O====If you want to use certbot's automatic renewal process==== */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line (keeping the indentation)<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
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<br />
$ sudo systemctl stop webwork2<br />
$ sudo certbot renew<br />
$ sudo systemctl start webwork2<br />
Note that if you just want to test the renewal process without actually renewing, run<br />
$ sudo certbot renew --dry-run<br />
instead. <br />
=====If you want to use certbot's automatic renewal process=====<br />
one option is to edit webwork2.mojolicious.yml and comment out the line <br />
- http://*:80<br />
so it reads<br />
# - http://*:80<br />
and a few lines above this change<br />
redirect_http_to_https: 1<br />
to<br />
redirect_http_to_https: 0<br />
and restart the webwork2 app<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
Now test this with<br />
$ sudo certbot renew --dry-run<br />
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 probably the preferred method.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24249WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-23T16:49:34Z<p>Apizer: /* Renewing the certificate */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line (keeping the indentation)<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
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<br />
$ sudo systemctl stop webwork2<br />
$ sudo certbot renew<br />
$ sudo systemctl start webwork2<br />
Note that if you just want to test the renewal process without actually renewing, run<br />
$ sudo certbot renew --dry-run<br />
instead. <br />
=O====If you want to use certbot's automatic renewal process=====<br />
one option is to edit webwork2.mojolicious.yml and comment out the line <br />
- http://*:80<br />
so it reads<br />
# - http://*:80<br />
and a few lines above this change<br />
redirect_http_to_https: 1<br />
to<br />
redirect_http_to_https: 0<br />
and restart the webwork2 app<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
Now test this with<br />
$ sudo certbot renew --dry-run<br />
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 probably the preferred method.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24246WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T18:46:28Z<p>Apizer: /* Renewing the certificate */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line (keeping the indentation)<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
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<br />
$ sudo systemctl stop webwork2<br />
$ sudo certbot renew<br />
$ sudo systemctl start webwork2<br />
Note that if you just want to test the renewal process without actually renewing, run<br />
$ sudo certbot renew --dry-run<br />
instead. If you want to use certbot's automatic renewal process, one option is to edit webwork2.mojolicious.yml and comment out the line <br />
- http://*:80<br />
so it reads<br />
# - http://*:80<br />
and a few lines above this change<br />
redirect_http_to_https: 1<br />
to<br />
redirect_http_to_https: 0<br />
and restart the webwork2 app<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
Now test this with<br />
$ sudo certbot renew --dry-run<br />
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 probably the preferred method.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24245WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T18:44:41Z<p>Apizer: /* Renewing the certificate */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line (keeping the indentation)<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
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<br />
$ sudo systemctl stop webwork2<br />
$ sudo certbot renew<br />
$ sudo systemctl start webwork2<br />
Note that if you just want to test the renewal process without actually renewing, run<br />
$ sudo certbot renew --dry-run<br />
instead. If you want to use certbot's automatic renewal process, one option is to edit webwork2.mojolicious.yml and comment out the line <br />
- http://*:80<br />
so it reads<br />
# - http://*:80<br />
and a few lines above this change<br />
redirect_http_to_https: 1<br />
to<br />
redirect_http_to_https: 0<br />
and restart the webwork2 app<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
Now test this with<br />
$ sudo certbot renew --dry-run<br />
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 may be the preferred method.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24244WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T18:40:13Z<p>Apizer: /* Renewing the certificate */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line (keeping the indentation)<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
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<br />
$ sudo systemctl stop webwork2<br />
$ sudo certbot renew<br />
$ sudo systemctl start webwork2<br />
Note that if you just want to test the renewal process without actually renewing, run<br />
$ sudo certbot renew --dry-run<br />
instead. If you want to use certbot's automatic renewal process, one option is to edit webwork2.mojolicious.yml and comment out the line <br />
- http://*:80<br />
so it reads<br />
# - http://*:80<br />
and a few lines above this change<br />
redirect_http_to_https: 1<br />
to<br />
redirect_http_to_https: 0<br />
and restart the webwork2 app<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
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 may be the preferred method.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24243WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T18:26:18Z<p>Apizer: /* Renewing the certificate */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line (keeping the indentation)<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
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<br />
$ sudo systemctl stop webwork2<br />
$ sudo certbot renew<br />
$ sudo systemctl start webwork2<br />
Note that if you just want to test the renewal process without actually renewing, run<br />
$ sudo certbot renew --dry-run<br />
instead. If you really want to use certbot's automatic renewal process, one option is to edit webwork2.mojolicious.yml and comment out the line <br />
- http://*:80<br />
so it reads<br />
# - http://*:80<br />
and a few lines above this change<br />
redirect_http_to_https: 1<br />
to<br />
redirect_http_to_https: 0<br />
and restart the webwork2 app<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
Note that this means students will need to use https: to connect to your server and will get an error message (which they may not understand) if they use http:<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24242WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T18:25:18Z<p>Apizer: /* Renewing the certificate */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line (keeping the indentation)<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
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<br />
$ sudo systemctl stop webwork2<br />
$ sudo certbot renew<br />
$ sudo systemctl start webwork2<br />
Note that if you just want to test the renewal process without actually renewing, run<br />
$ sudo certbot renew --dry-run<br />
instead. If you really want to use certbot's automatic renewal process, one option is to edit webwork2.mojolicious.yml and comment out the line <br />
- http://*:80<br />
so it reads<br />
# - http://*:80<br />
and a few lines above this change<br />
redirect_http_to_https: 1<br />
to<br />
redirect_http_to_https: 0<br />
and restart the webwork2 app<br />
$ sudo systemctl restart webwork2<br />
Note that this means students will need to use https: to connect to your server and will get an error message (which they may not understand) if they use http:<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24241WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T18:24:40Z<p>Apizer: /* Renewing the certificate */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line (keeping the indentation)<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
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<br />
$ sudo systemctl stop webwork2<br />
$ sudo certbot renew<br />
$ sudo systemctl start webwork2<br />
Note that if you just want to test the renewal process without actually renewing, run<br />
$ sudo certbot renew --dry-run<br />
instead. If you really want to use certbot's automatic renewal process, one option is to edit webwork2.mojolicious.yml and comment out the line <br />
- http://*:80<br />
so it reads<br />
# - http://*:80<br />
and a few lines above this change<br />
redirect_http_to_https: 1<br />
to<br />
redirect_http_to_https: 0<br />
and restart the webwork2 app<br />
$ sudo systemctl restart webwork2<br />
Note that this means students will need to use https: to connect to your server and will get an error message (which they may not understand) if they use http:<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24240WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T18:22:55Z<p>Apizer: /* Now we we configure the webwork2 app to use SSL */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line (keeping the indentation)<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
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<br />
$ sudo systemctl stop webwork2<br />
$ sudo certbot renew<br />
$ sudo systemctl start webwork2<br />
Note that if you just want to test the renewal process without actually renewing, run<br />
$ sudo certbot renew --dry-run<br />
instead. If you really want to use certbot's automatic renewal process, one option is to edit webwork2.mojolicious.yml and comment out the line <br />
- http://*:80<br />
so it reads<br />
# - http://*:80<br />
and a few lines above this change<br />
redirect_http_to_https: 1<br />
to<br />
redirect_http_to_https: 0<br />
Note that this means students will need to use https: to connect to your server and will get an error message (which they may not understand) if they use http:<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24239WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T18:18:46Z<p>Apizer: /* Renewing the certificate */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
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<br />
$ sudo systemctl stop webwork2<br />
$ sudo certbot renew<br />
$ sudo systemctl start webwork2<br />
Note that if you just want to test the renewal process without actually renewing, run<br />
$ sudo certbot renew --dry-run<br />
instead. If you really want to use certbot's automatic renewal process, one option is to edit webwork2.mojolicious.yml and comment out the line <br />
- http://*:80<br />
so it reads<br />
# - http://*:80<br />
and a few lines above this change<br />
redirect_http_to_https: 1<br />
to<br />
redirect_http_to_https: 0<br />
Note that this means students will need to use https: to connect to your server and will get an error message (which they may not understand) if they use http:<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24238WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T18:13:31Z<p>Apizer: /* Renewing the certificate */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
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<br />
$ sudo systemctl stop webwork2<br />
$ sudo certbot renew<br />
$ sudo systemctl start webwork2<br />
Note that if you just want to test the renewal process without actually renewing, run<br />
$ sudo certbot renew --dry-run<br />
instead. If you really want to use certbot's automatic renewal process, one option is to edit<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24237WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T17:51:11Z<p>Apizer: /* Edit webwork2.mojolicious.yml */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
<br />
For information on renewing your certificate, see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=8299&parent=20775#p20792. Note that I have not tested this.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24236WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T17:48:49Z<p>Apizer: /* Next we create our SLL certificate and key */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported this was a problem when they ran certbot so it is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
<br />
For information on renewing your certificate, see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=8299&parent=20775#p20792. Note that I have not tested this.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24235WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T17:47:47Z<p>Apizer: /* Next we create our SLL certificate and key */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
drwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported that was a problem when they ran certbot so is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
<br />
For information on renewing your certificate, see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=8299&parent=20775#p20792. Note that I have not tested this.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24234WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T17:45:00Z<p>Apizer: /* Next we create our SLL certificate and key */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
I have done this twice and in one case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but in the other case there was a problem e.g<br />
ls -l /etc/letsencrypt/<br />
drwx------ 3 root root 4096 Oct 22 17:29 archive/<br />
rwx------ 3 root root 4096 Oct 22 17:29 live/<br />
so I had to run<br />
cd /etc/letsencrypt/<br />
sudo chmod 755 *<br />
Note that several others have reported that was a problem when they ran certbot so is something to definitely check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
<br />
For information on renewing your certificate, see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=8299&parent=20775#p20792. Note that I have not tested this.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24233WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T15:05:16Z<p>Apizer: /* Checking for and Installing Hotfixes */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 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.<br />
$ exit<br />
$ sudo systemctl restart webwork2<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
<br />
For information on renewing your certificate, see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=8299&parent=20775#p20792. Note that I have not tested this.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24232WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T15:00:21Z<p>Apizer: /* Checking for and Installing Hotfixes */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
--><br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
<br />
For information on renewing your certificate, see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=8299&parent=20775#p20792. Note that I have not tested this.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24231WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-22T14:56:16Z<p>Apizer: /* Connection Problems */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
<br />
For information on renewing your certificate, see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=8299&parent=20775#p20792. Note that I have not tested this.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24222WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-19T19:39:04Z<p>Apizer: /* Renewing the certificate */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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 need to be added or edited, select the "Security groups" number, "Edit inbound rules" and then edit and/or "Add rule".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
<br />
For information on renewing your certificate, see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=8299&parent=20775#p20792. Note that I have not tested this.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24221WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-19T19:38:38Z<p>Apizer: /* Renewing the certificate */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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 need to be added or edited, select the "Security groups" number, "Edit inbound rules" and then edit and/or "Add rule".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
<br />
For information on renewing your certificate, see <nowiki>https://webwork.maa.org/moodle/mod/forum/discuss.php?d=8299&parent=20775#p20792</nowiki>. Note that I have not tested this.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24220WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-19T19:34:36Z<p>Apizer: /* Test that all is well */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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 need to be added or edited, select the "Security groups" number, "Edit inbound rules" and then edit and/or "Add rule".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
====Renewing the certificate====<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24215WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-10-02T13:15:15Z<p>Apizer: /* Connection Problems */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
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 need to be added or edited, select the "Security groups" number, "Edit inbound rules" and then edit and/or "Add rule".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24191WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-09-14T18:05:44Z<p>Apizer: /* Network Settings */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
'''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".<br />
<br />
If you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
If you have problems connecting the first think 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 need to be added or edited, select the "Security groups" number, "Edit inbound rules" and then edit and/or "Add rule".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24190WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-09-14T17:56:36Z<p>Apizer: /* Network Settings */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
Note that if you do not see information about SSH and you have problems connecting to your server, see the section [[#Connection Problems|Connection Problems]] below.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
If you have problems connecting the first think 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 need to be added or edited, select the "Security groups" number, "Edit inbound rules" and then edit and/or "Add rule".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24189WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-09-14T17:53:44Z<p>Apizer: /* Network Settings */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can create a security group or use an existing one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
Allow SSH (which you will use for direct terminal access to your server) which is probably already set up with source <code>0.0.0.0/0</code>. 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
If you have problems connecting the first think 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 need to be added or edited, select the "Security groups" number, "Edit inbound rules" and then edit and/or "Add rule".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24188WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-09-14T17:13:12Z<p>Apizer: /* Connection Problems */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can use the default security group or create a new one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
SSH (which you will use for direct terminal access to your server) 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" 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
If you have problems connecting the first think 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 need to be added or edited, select the "Security groups" number, "Edit inbound rules" and then edit and/or "Add rule".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24187WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-09-14T16:13:57Z<p>Apizer: /* Connection Problems */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can use the default security group or create a new one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
SSH (which you will use for direct terminal access to your server) 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" 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
If you have problems connecting the first think 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 need to be added or edited, select the "Security groups" number, "Edit inbound rules" and then edit and/or "Add rule".<br />
<br />
If the inbound rules are not your problem look at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html<br />
for further help.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24186WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-09-14T16:03:41Z<p>Apizer: /* Accessing Your Server from a Terminal Emulator on your Host */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can use the default security group or create a new one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
SSH (which you will use for direct terminal access to your server) 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" 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
====Connection Problems====<br />
If you have problems connecting the first think to check is that ports 22 (and 80 and 443) are open for inbound connections and are accessible from your location.<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Virtual_Machine_Image&diff=24185WeBWorK 2.18 Ubuntu Server 22.04 LTS Virtual Machine Image2023-09-13T13:15:13Z<p>Apizer: /* Adjust the mojolicious.yml configuration according to your server's memory */</p>
<hr />
<div><!--<br />
{{UnderConstruction}} <br />
--><br />
<br />
These instructions cover the installation of the Ubuntu Server 22.04 LTS 64 bit operating system and WeBWorK 2.18 using the WeBWorK Virtual Machine Image. <br />
<br />
The WeBWorK Virtual Machine Image is an <code>.ova</code> file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, QEMU/KVM, etc. <br />
<br />
This image file has been tested on <br />
* VMware Workstation 17 Player<br />
* VirtualBox 7<br />
* QEMU/KVM running on a Ubuntu 22.04 Desktop host<br />
<br />
This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc.) installed and configured. <br />
<br />
== Installing from WW2.18 Ubuntu22.04 Server Virtual Machine Image ==<br />
<br />
===Overview===<br />
After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who has sudo privileges), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> who has professor privileges and also the Mjolicious secret (see below).<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]].<br />
<br />
===Download the ova image===<br />
<br />
Download the sha256 checksum and the .ova files from the WeBWorK Download Site below. <br />
<br />
You want to download the files <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code> and <code>WW2.18_Ubuntu22.04_Server.ova</code><br />
The ova is a 7.3 GB file.<br />
<br />
* [http://webwork.maa.org/ww-downloads/wwdownload.html WeBWorK Download Site]<br />
<br />
Verify the SHA256 checksum of your downloaded file <code>WW2.18_Ubuntu22.04_Server.ova</code> agrees with the one in <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code>.<br />
<br />
===OVA and OVF files===<br />
The <code>.ova</code> file is simply a tar bundle containing an <code>.ovf</code> file, one or more <code>.vmdk</code> files, a <code>.mf</code> file and possibly other files.<br />
* The <code>.ovf</code> file is an XML file which describes the packaged virtual machine and is human-readable. <br />
* The <code>.vmdk</code> file(s) contain the disk images(s).<br />
* Possibly other files<br />
* The <code>.mf</code> file contains SHA1 checksums for the above files.<br />
<br />
You can import a virtual machine either from an <code>.ova</code> file or from the <code>.ovf</code>, <code>.vmdk</code>, <code>.mf</code> collection. Sometimes importing from the <code>.ova</code> file may fail whereas importing from the <code>.ovf</code> or <code>.vmdk</code> file will succeed.<br />
<br />
You can extract the files in <code>WW2.18_Ubuntu22.04_Server.ova</code> with the command <br />
<br />
$ tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
<br />
You then can look at (and possibly edit) the human readable <code>WW2.18_Ubuntu22.04_Server.ofv</code> file. If you do edit the <code>WW2.18_Ubuntu22.04_Server.ofv</code> file, you will also have to compute the new SHA1 checksum and replace the old one in the <code>WW2.18_Ubuntu22.04_Server.mf</code> file for the files to be usable.<br />
<br />
===Installing the WeBWorK Virtual Machine Image ===<br />
<br />
Import the file <code>WW2.18_Ubuntu22.04_Server.ova</code> into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 17 Player <br />
running on a Windows 11 Pro host. It has been tested on <br />
* VMware Workstation 17 Player running on a Windows 11 host (Pro edition)<br />
* VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host<br />
* VirtualBox 7 running on a Windows 11 host (Home and Pro editions)<br />
* VirtualBox 7 running on a Ubuntu 22.04 Desktop host<br />
* QEMU/KVM running on a Ubuntu 22.04 Desktop host<br />
'''See [[#Specific Virtual Environments|Specific Virtual Environments]] below for installation information on specific virtual environments.'''<br />
<br />
====Processors, Memory, Hard Disk, Networking====<br />
The WeBWorK Virtual Machine Image was created with the following parameters:<br />
*20 GB dynamically allocated disk drive in VMDK format (single file) of which 13 GB is used<br />
*4 GB memory<br />
*2 cpu<br />
These resources are OK for testing and may suffice for a very small course but it is possible to overwhelm the machine. <br />
<br />
Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 17 Player running on a Windows 11 host). You should adjust these resources either when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk is more complicated. See [[#Specific Virtual Environments|Specific Virtual Environments]] below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see [[#Increase Disk Space|Increase Disk Space]] below). <br />
<br />
Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]) and/or look at [[#Debugging Networking Issues|Debugging Networking Issues]].<br />
<br />
===Import the .ova file===<br />
There may be specific information for your situation below. See<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 7 running on a Ubuntu 22.04 Desktop host|VirtualBox 7 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
* [[#Amazon EC2|Amazon EC2]]<br />
<br />
===Your server===<br />
After importing, your virtual WeBWorK server will be identical to a system created by following the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] with the Webwork2 Mojolicious App being served directly via hypnotoad (option 1) and the Optional Configurations B and C implemented. '''Note that''' Option A (SSL) is not implemented (see [[#Set up WeBWorK to use SSL|Set up WeBWorK to use SSL]] below).<br />
<br />
'''Note''' that on some virtual environments, you may need to take additional actions. See the section [[#Specific Virtual Environments|Specific Virtual Environments]] below.<br />
<br />
You should read through the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] in order to understand how your server has been set up. Especially look at<br />
[[Installation Manual for 2.18 on Ubuntu#Notation|Notation in the Installation Manual for 2.18 on Ubuntu]] to understand the notation we use in these instructions.<br />
<br />
==Boot Your Server==<br />
===Log into your server ===<br />
After booting you should see a login prompt (you may have to press <code>&lt;Enter&gt;</code>).<br />
*Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges. We will denote<br />
wwadmin's password by <code><wwadmin password></code>. Initially this is set to <code>wwadmin</code>.<br />
If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.<br />
<br />
===Test your ip address===<br />
Run the command<br />
$ ip address show<br />
and look at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]). If that doesn't help look at [[#Debugging Networking Issues|Debugging Networking Issues]]. '''You have to fix this before you can go on to the next step'''.<br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program. <br />
<br />
You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with <code>copy</code> from the Edit menu or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit menu list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code> or <code>&lt;Shift&gt; &lt;Insert&gt;</code> depending on your application). <br />
<br />
My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. In any event, after testing, read the section [[#Make the WeBWorK Configuration Permanent|Make the WeBWorK Configuration Permanent]] below. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.<br />
<br />
I am assuming your network has been set up automatically.<br />
<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a <br />
terminal emulator running on your host using ssh, or from the terminal on the guest once you login. <br />
<br />
Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will probably see <br />
...<br />
Time zone: Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/New_York". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/New_York<br />
[sudo] password for wwadmin: <wwadmin password><br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
=== Checking for and Installing Hotfixes ===<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check_for_and_Install_Hotfixes in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
'''Important: The are bug fixes for both the webwork2 code and the pg code that occurred after the virtual machine image was built. You should definitely update both the webwork2 and pg code.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the virtual machine image was built. <br />
You should definitely update the webwork2 code.'''<br />
--><br />
<!--<br />
'''Important: The are bug fixes for the pg code that occurred after the virtual machine image was built. You should definitely update the pg code.'''<br />
--><br />
<br />
=== WeBWorK configuration ===<br />
<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
First we have to edit information about the network server setup. <br />
Search for <code>192.168.138.131</code> and replace that by your the new ip address you found above (<code>192.168.76.128</code> in our example above). <br />
<br />
'''But wait, this can be tricky'''. If you set up port forwarding (as we had to for VirtualBox), then instead use the code<br />
$server_root_url = 'http://localhost';<br />
<br />
The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM)<br />
<br />
$server_root_url = 'http://192.168.76.128';<br />
<br />
where of course your ip address may be different. The "http://" is important. <br />
<br />
'''Remark'''. First of all, let me admit I don't understand the above - it just works. If this is not set correctly (and I don't really understand what "correctly" means), then when you test the Library Browser, e.g. by clicking on <code>Library Browser</code> on the <code>Main Menu</code>, then on <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, you will not be able to select a <code>Chapter</code> and you will see an error message similar to<br />
183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.<br />
If you google this message, you will find a lot of people have seen this error and the most common reason is that <code>$server_root_url</code> has not been set correctly, whatever "correctly" means. A common error is to forget <code>http://</code> or to use <code>http://</code> when you should use <code>https://</code> (or vice versa) or to just have the wrong domain name or ip address.<br />
<br />
We now continue editing <code>site.conf</code> <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then.<br />
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.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.'''<br />
<br />
Then save the file and Quit. And restart the webwork2 app so that these changes take effect:<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
===Set up WeBWorK to use SSL===<br />
This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.<br />
<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Implement Option A (SSL)|Implement Option A (SSL) in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
Note that the Virtual Machine Image was built using Option 1: Serving Directly via Hypnotoad so that in the instructions for setting up SSL follow the section<br />
Set up Hypnotoad to use SSL (Option 1).<br />
<br />
===Finish up===<br />
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.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://192.168.76.128/webwork2</code> where of course you should use your actual ip address. If you have already set up https and haven't setup the redirect, then you should use <code>https://192.168.76.128/webwork2</code> . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.<br />
<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Make the WeBWorK Configuration Permanent==<br />
<br />
Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with <code>ip address show</code>) and used that when editing the <code>site.conf</code> file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.<br />
# The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the <code>site.conf</code> file. <br />
# The other method is to setup networking to use a fixed specific ip address for your server and use that in the <code>site.conf</code> file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the [[#Networking_2|Networking]] section under [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] below for information on editing these files. You can search the web for information on the correct syntax to use.<br />
<br />
Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections [[#Edit the site.conf file|Edit the site.conf file]] and [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]].<br />
<br />
Remember that any time you edit WeBWorK's configuration files, you have the restart the WeBWorK2 app for the changes to take effect; see [[Installation_Manual_for_2.18_on_Ubuntu#Enable_and_start_the_Webwork2_Systemd_Service|Enable_and_start_the_Webwork2_Systemd_Service in the Installation Manual for 2.18 on Ubuntu]]. For networking changes to take effect, you should reboot the server.<br />
<br />
==Passwords==<br />
It is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access.<br />
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. Also change the mojolicious.yml secret.<br />
====Change the mojolicious.yml secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
====Change the password for wwadmin====<br />
<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$ <br />
'''Do not forget the new <code>&lt;wwadmin password&gt;</code> that you just entered.''' Below when we refer to <wwadmin password>, we mean the '''new''' <wwadmin password>.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = "wwadmin";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. We refer to this password as <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart webwork2 so the changes take effect.<br />
<br />
$ sudo systemctl restart webwork2<br />
[sudo] password for wwadmin: <wwadmin password><br />
$<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,authentication_string,password,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <code>webworkWrite</code> should have <br />
a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT Host, User, password FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
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.<br />
<br />
====Change the password for profa====<br />
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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
http://192.168.76.128/webwork2/admin</code> <br />
http://192.168.76.128/webwork2/mytestcourse</code> <br />
where of course you should use your actual ip address.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in [[#Specific Virtual Environments|Specific Virtual Environments]] below. <br />
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<br />
20 GB to 30GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 19G 11G 7.3G 59% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/sda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 21.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags: <br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 20.0GB 20.0GB ext4<br />
<br />
(parted)<br />
<br />
We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command<br />
(parted) resizepart<br />
Partition number? 2<br />
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [20GB]? 30GB<br />
(parted)<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 31.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags:<br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 30.0GB 30.0GB ext4<br />
<br />
(parted)<br />
Notice we now have a 30 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below<br />
$ sudo resize2fs /dev/sda2<br />
[sudo] password for wwadmin: <wwadmin password><br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/sda2 is mounted on /; on-line resizing required<br />
old_desc_blocks = 2, new_desc_blocks = 3<br />
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 29G 11G 18G 38% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
*'''Option A''' is not implemented. '''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
==Specific Virtual Environments==<br />
Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of<br />
the specific environments we have information on:<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 15 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
<br />
===VMware Workstation 17 Player running on a Windows 11 host===<br />
====Importing the ova File====<br />
For VMware Player select Player, File, Open and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file.<br />
Name your machine and select a storage path and then hit Import<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
====Accessing your server from your host====<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the '''WeBWorK Placeholder Page'''. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the '''WeBWorK''' Welcome page. <br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 17 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Windows 11 host===<br />
<br />
====Importing the ova File====<br />
For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file. Click Finish. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Initially networking will be broken. Do the following from your guest WeBWorK system<br />
$ sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
...<br />
logical name: enp0s17<br />
version: 02<br />
serial: 08:00:27:30:28:b6<br />
...<br />
Remember the logical name from your system as we will need it below. We have to backup and then edit one file.<br />
<br />
$ cd /etc/netplan/<br />
$ sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak1<br />
[sudo] password for wwadmin: <wwadmin password> <br />
Now edit the <code> 00-installer-config.yaml</code> file<br />
$ sudo nano 00-installer-config.yaml<br />
It should look like (I had to stretch the window to see the whole file):<br />
# This is the network config written by 'subiquity'<br />
network:<br />
ethernets:<br />
ens33:<br />
dhcp4: true<br />
version: 2<br />
Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.<br />
<br />
<br />
Now reboot your server,e.g.<br />
$ sudo reboot<br />
[sudo] password for wwadmin: <wwadmin password> <br />
login and run the command<br />
$ ip address show<br />
and look at the output, something like<br />
... <br />
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000<br />
link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff<br />
inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17<br />
...<br />
<br />
We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below. <br />
<br />
In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network"<br />
Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:<br />
<br />
{| class="wikitable"<br />
|+Port Forwarding<br />
!Name<br />
!Protocol<br />
!Host IP<br />
!Host Port<br />
!Guest IP<br />
!Guest Port<br />
|-<br />
|ssh<br />
|TCP<br />
|127.0.0.1<br />
|2222<br />
|10.0.2.15<br />
|22<br />
|-<br />
|https<br />
|TCP<br />
|127.0.0.1<br />
|4443<br />
|10.0.2.15<br />
|443<br />
|-<br />
|http<br />
|TCP<br />
|127.0.0.1<br />
|8081<br />
|10.0.2.15<br />
|80<br />
|}<br />
Double check that you have entered everything correctly ('''using''' your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".<br />
<br />
Now boot your server.<br />
<br />
====Accessing your server from your host====<br />
We need to employ the port forwarding rules above.<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up with the port forwarding rules above, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and you should the '''WeBWorK''' Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.<br />
<br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your guest is shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list <br />
(probably "WW2.18_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. <br />
Click “Apply” when you're done.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host===<br />
<br />
====Importing the ova File====<br />
For VMware Player select File, Open a Virtual Machine and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and import the file.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
Accessing your server is exactly the same as in [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]] above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.76.128<br />
where of course you need to use the ip address of your WeBWorK guest server.<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Ubuntu 22.04 Desktop host===<br />
====Importing the ova File====<br />
Importing the ova File is exactly the same as in [[#VirtualBox 76 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card)<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
# Set up port forwarding<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details.<br />
<br />
'''Except''' that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh -p 2222 wwadmin@127.0.0.1<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
The procedure is the same as in [[#Expand the disk drive_2|Expand the disk drive]] the Windows 11 case above.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===QEMU/KVM running on a Ubuntu 22.04 Desktop host===<br />
====First install Qemu-KVM====<br />
<br />
It is probably a good idea to first update and upgrade the system packages:<br />
$ sudo apt update<br />
$ sudo apt upgrade<br />
<br />
Now install Qemu-KVM<br />
$ sudo apt install -y qemu-kvm virt-manager libvirt-daemon-system virtinst libvirt-clients bridge-utils<br />
<br />
Enable and start libvirtd<br />
$ sudo systemctl enable --now libvirtd<br />
$ sudo systemctl start libvirtd<br />
and check that all is OK<br />
$ sudo systemctl status libvirtd<br />
<br />
Now add wwadmin to the kvm and libvirt groups.<br />
$ sudo usermod -aG kvm $USER<br />
$ sudo usermod -aG libvirt $USER<br />
<br />
====Convert the image to qcow2 format====<br />
<br />
cd to whatever directory you downloaded the <code>WW2.18_Ubuntu22.04_Server.ova</code> file to (maybe "Downloads") and then untar it<br />
tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
which might take awhile. Then run the command to covert the vmdk format to qcow2 format<br />
qemu-img convert -p -f vmdk -O qcow2 WW2.18_Ubuntu22.04_Server-disk1.vmdk WW2.18_Ubuntu22.04_Server.qcow2<br />
and move the qcow2 image to the correct location<br />
sudo mv WW2.18_Ubuntu22.04_Server.qcow2 /var/lib/libvirt/images/<br />
<br />
====Boot up your virtual machine====<br />
Start up Virtual Machine Manager (search for VM in the app manager). Note that if you run into problems running the Virtual Machine Manager (e.g. QEMU/KVM not connected), the first thing to try is rebooting your host machine.<br />
<br />
In the Virtual Machine Manager,<br />
select File, New Virtual Machine, Import existing disk image, Forward, Browse and finally select WW2.18_Ubuntu22.04_Server.qcow2. The select Choose Volume and enter Ubuntu 22.04 LTS for the operating system you are installing. Next click Forward and choose your memory and CPUs. Select Forward again, name your system and finally select finish.<br />
<br />
Now log into your virtual machine (wwadmin with password wwadmin)<br />
<br />
====Networking====<br />
<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card), probably something like enp1s0<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details '''except that'''<br />
# You do not need port forwarding<br />
# Instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.122.233<br />
(where of course you need to use the actual ip address of your guest WeBWorK server).<br />
<br />
====Expand the disk drive====<br />
You can do most of this from the graphical Virtual Machine Manager (select the machine, then Edit, Virtual Machine Details). Below are commands to this from the command line. I think you have to actually expand the disk from the command line but you can get information and add cpu's and/or memory from the graphical Virtual Machine Manager.<br />
<br />
I'm assume the name of your WeBWorK guest is <code>wwserver</code> and it is Shutoff. First find the location of the disk.<br />
Run the command<br />
$ sudo virsh domblklist wwserver<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
Target Source<br />
-------------------------------------------------------------------------<br />
sda /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
<br />
Now get some info about the disk<br />
$ sudo qemu-img info /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
image: /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
file format: qcow2<br />
virtual size: 12 GiB (12884901888 bytes)<br />
disk size: 6.76 GiB<br />
cluster_size: 65536<br />
Format specific information:<br />
compat: 1.1<br />
lazy refcounts: false<br />
refcount bits: 16<br />
corrupt: false<br />
<br />
and now lets resize it to 20 GB by adding 8 GB<br />
sudo qemu-img resize /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2 +8G<br />
[sudo] password for wwadmin: <wwadmin password><br />
Image resized.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===Amazon EC2===<br />
While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the [[WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image]] is faster and easier anyway.<br />
<br />
==Debugging Networking Issues==<br />
If after reading the information above on networking you are still having problems, maybe the information below will be of help.<br />
<br />
===One method===<br />
There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms:<br />
$ ip address show<br />
does not return an ip address and the WW guest can not access the outside world.<br />
<br />
In VirtualBox I built another guest from the <code>ubuntu-22.04-live-server-amd64.iso</code> using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by<br />
sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files<br />
/etc/netplan/00-installer-config.yaml<br />
and<br />
/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg<br />
BUT in the WW guest the information did not agree. This led to the information given in [[#Networking_2|the Networking section of VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
===Ports on your WeBWorK guest===<br />
Run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you see something like<br />
<br />
systemd-r 697 systemd-resolve 13u IPv4 19596 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
sshd 772 root 3u IPv4 21834 0t0 TCP *:22 (LISTEN)<br />
sshd 772 root 4u IPv6 21845 0t0 TCP *:22 (LISTEN)<br />
lighttpd 810 www-data 4u IPv4 22509 0t0 TCP *:8080 (LISTEN)<br />
mysqld 856 mysql 31u IPv6 23312 0t0 TCP *:33060 (LISTEN)<br />
mysqld 856 mysql 33u IPv4 23654 0t0 TCP 127.0.0.1:3306 (LISTEN)<br />
Rserve 865 rserveuser 3u IPv4 22878 0t0 TCP 127.0.0.1:6311 (LISTEN)<br />
/usr/sbin 946 root 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 956 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 957 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 958 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 959 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 960 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
<br />
===Ports on your Windows 11 Pro host===<br />
Open a Power Shell command window as an administrator and run the command (it can take awhile)<br />
PS C:\> netstat -ab<br />
<br />
Active Connections<br />
<br />
Proto Local Address Foreign Address State<br />
TCP 0.0.0.0:135 desktop:0 LISTENING<br />
RpcSs<br />
[svchost.exe]<br />
TCP 0.0.0.0:443 desktop:0 LISTENING<br />
[vmware-hostd.exe]<br />
TCP 0.0.0.0:445 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:903 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:913 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:2869 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:3306 desktop:0 LISTENING<br />
[mysqld.exe]<br />
...<br />
TCP 0.0.0.0:6000 desktop:0 LISTENING<br />
[XWin_MobaX.exe]<br />
TCP 0.0.0.0:49664 desktop:0 LISTENING<br />
...<br />
TCP 127.0.0.1:2222 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52916 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52917 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:4443 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
...<br />
<br />
===Ports on your Linux host===<br />
<br />
Run the command<br />
<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for ****: <br />
<br />
and you should see something like the following<br />
systemd-r 436 systemd-resolve 13u IPv4 18620 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
vmware-au 1284 root 10u IPv6 33012 0t0 TCP *:902 (LISTEN)<br />
vmware-au 1284 root 11u IPv4 33013 0t0 TCP *:902 (LISTEN)<br />
sshd 8786 root 3u IPv4 114131 0t0 TCP *:22 (LISTEN)<br />
sshd 8786 root 4u IPv6 114133 0t0 TCP *:22 (LISTEN)<br />
cupsd 12124 root 6u IPv6 138503 0t0 TCP [::1]:631 (LISTEN)<br />
cupsd 12124 root 7u IPv4 138504 0t0 TCP 127.0.0.1:631 (LISTEN)<br />
VirtualBo 17065 wwadmin 48u IPv4 185297 0t0 TCP 127.0.0.1:8081 (LISTEN)<br />
VirtualBo 17065 wwadmin 49u IPv4 185298 0t0 TCP 127.0.0.1:4443 (LISTEN)<br />
VirtualBo 17065 wwadmin 50u IPv4 185299 0t0 TCP 127.0.0.1:8080 (LISTEN)<br />
VirtualBo 17065 wwadmin 51u IPv4 185300 0t0 TCP 127.0.0.1:2222 (LISTEN)<br />
<br />
Notice that port forwarding for VirtualBox has been set up correctly.<br />
<br />
<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24184WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-09-12T21:14:39Z<p>Apizer: /* Changing the instance type */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can use the default security group or create a new one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
SSH (which you will use for direct terminal access to your server) 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" 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits | Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24183WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-09-12T21:13:33Z<p>Apizer: /* Changing the instance type */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can use the default security group or create a new one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
SSH (which you will use for direct terminal access to your server) 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" 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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. <br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory | Adjust Hypnotoad's configuration according to your server's memory]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24182WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-09-12T21:12:19Z<p>Apizer: /* Adjust Hypnotoad's configuration according to your server's memory */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can use the default security group or create a new one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
SSH (which you will use for direct terminal access to your server) 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" 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory and also adjust connection limits===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory | Adjust Hypnotoad's configuration according to your server's memory]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24181WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-09-12T21:11:32Z<p>Apizer: /* Adjust Hypnotoad's configuration according to your server's memory */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can use the default security group or create a new one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
SSH (which you will use for direct terminal access to your server) 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" 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there. You may also have to adjust the number of database connections, see [[Installation_Manual_for_2.18_on_Ubuntu#Connection_Limits|Connection_Limits in the Installation Manual for 2.18 on Ubuntu 22.04 Server]]<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory | Adjust Hypnotoad's configuration according to your server's memory]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image&diff=24180WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image2023-09-12T20:56:46Z<p>Apizer: /* Edit the site.conf file */</p>
<hr />
<div><br />
<!-- {{UnderConstruction}} --><br />
<br />
These instructions cover setting up WeBWorK 2.18 using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI (Amazon Machine Image). <br />
<br />
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. <br />
<br />
== Setting up the WeBWorK 2.18 Ubuntu Server 22.04 LTS Amazon Machine Image ==<br />
<br />
===Overview===<br />
After using the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> Amazon Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured.<br />
<br />
It is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who owns most WeBWorK files), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> 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.<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]]. The AMI (Amazon Machine Image) was built following those instructions.<br />
<br />
===First you need an AWS account===<br />
<br />
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/.<br />
<br />
===Find the AMI image===<br />
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 <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> listed.<br />
<br />
'''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".<br />
<br />
===Configure the WeBWorK AMI Image ===<br />
<br />
Select the <code>WeBWorK 2.18 on Ubuntu Server 22.04 LTS</code> AMI and hit <code>Launch instance from AMI</code><br />
<br />
====Name and tags====<br />
Name the instance and add additional tags if you want.<br />
<br />
====Choose an Instance Type====<br />
<br />
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.<br />
<br />
The WeBWorK AMI was built from a t3.small ec2 instance having the following resources: <br />
*20 GB disk drive of which about 8 GB is used<br />
*2 GB memory<br />
*2 (virtual) cpu<br />
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.<br />
<br />
The Mathematical Association of America (MAA) courses1 server (which is no longer in use) was a t2.2xlarge ec2 instance having the following resources: <br />
*70 GB disk drive<br />
*32 GB memory<br />
*8 (virtual) cpu's<br />
<br />
The MAA courses1 server was hosting over 600 courses of which around 150 were active in June, 2020. <br />
<br />
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 | 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.<br />
<br />
====Select or Create a key pair====<br />
A key pair is used to securely log into your server.<br />
Create a new key pair or use an existing one. Download and save the pem file (e.g. WWsecretkey.pem).<br />
<br />
====Network Settings====<br />
You can use the default security group or create a new one. <br />
<br />
You also should create inbound rules so that you and others can communicate with your server instance.<br />
SSH (which you will use for direct terminal access to your server) 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" 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.<br />
SSH TCP 22 98.12.176.149/32 SSH for admin<br />
<br />
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. <code>0.0.0.0/0</code>. 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|Passwords]] below for information on users who already have simple non secure passwords that '''must''' be changed.<br />
<br />
You should also allow HTTPS although initially your server will not be setup for this.<br />
<br />
====Configure storage====<br />
<br />
You can change the amount of disk space. 20 GB is a reasonable amount to start with for a small server.<br />
<br />
==Launch Your Server==<br />
<br />
Click "Launch instance" to launch your instance<br />
<br />
Now Launch your server by clicking on "Launch instances". Clicking on the Instance ID is a fast way to get to your EC2 Dashboard. Or Click on "View all instances" <br />
<br />
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. <br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
<br />
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.<br />
<br />
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 <code>ubuntu</code> (no password required). Other terminal emulators (Putty, iTerm2, etc) will be similar. <br />
<br />
If you are using ssh in a terminal window, use the command<br />
<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
(you may have to provide the path to the WWsecretkey.pem file). <br />
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<br />
chmod 600 WWsecretkey.pem<br />
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<br />
<br />
cp WWsecretkey.pem ~/<br />
cd <br />
chmod 600 WWsecretkey.pem<br />
ssh -i WWsecretkey.pem ubuntu@18.216.251.98<br />
<br />
=== Users on your system ===<br />
There are two users who can login to the system: <code>ubuntu</code> and <code>wwadmin</code> <br />
====ubuntu====<br />
<code>ubuntu</code> is the "system" user who has sudo privileges. You probably always want to initially log in as <code>ubuntu</code> using the secret key file WWsecretkey.pem.<br />
=====Running commands as root=====<br />
By default your Ubuntu server has no password set for the root user. To gain root access you have to use the <code>sudo</code> command while logged in as <code>ubuntu</code>.<br />
<br />
To run commands as <code>root</code> use <br />
$ sudo <command><br />
A log of all <code>sudo</code> commands is kept in <code>/var/log/auth.log</code> . <br />
<br />
You can also use sudo to become root and get the root prompt #. To do this run<br />
$ sudo -s<br />
#<br />
When you want to exit the root prompt and return to being the regular user ubuntu, do the following<br />
# exit<br />
exit<br />
$<br />
<br />
====wwadmin====<br />
<code>wwadmin</code> 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 <code>su</code> (switch user) command to become <code>wwadmin</code>. The password for <code>wwadmin</code> is "wwadmin" so the command is:<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
After you have finished whatever you have to do as <code>wwadmin</code>, you can return to being the <code>ubuntu</code> user by <br />
$exit<br />
exit<br />
$<br />
<code>wwadmin</code> is not in the sudo group so if you want to use sudo, you have to be <code>ubuntu</code>.<br />
<br />
Also you should change the password for <code>wwadmin</code> to something much more secure than "wwadmin" (see [[#Passwords|Passwords]]).<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will see<br />
...<br />
Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/Los_Angeles". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/Los_Angeles<br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
==Checking for and Installing Hotfixes==<br />
'''To check for and/or install updates you will have to become the wwadmin user:'''<br />
$ su wwadmin<br />
Password: wwadmin<br />
$<br />
<br />
Then follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check for and Install Hotfixes in the Installation Manual for 2.18 on Ubuntu]]. Remember that you have to restart the webwork2 app after updating the webwork2 and/or pg code.<br />
<!--<br />
'''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.'''<br />
--><br />
<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the AMI was built. You should definitely update the webwork2 code.'''<br />
<br />
== Give your Instance a permanent IP address ==<br />
<br />
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.<br />
<br />
== WeBWorK Configuration ==<br />
===The WeBWorK URL===<br />
We need a WeBWorK URL to give to students and professors so that they can access WeBWorK.<br />
<br />
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.<br />
<br />
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). <br />
<br />
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.<br />
<br />
===The WeBWorK .conf files===<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
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. <br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
$ su wwadmin<br />
Password: wwadmin<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.117.176.238/</nowiki>';<br />
which you should replace with<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course replace <code>18.190.3.215</code> by your actual ip address. <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although you might want to hold off on this until you check that your server is functioning well.<br />
<br />
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.<br />
<br />
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 <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.''' <br />
<br />
If you do not use your school's SMTP server, the following documentation may be helpful:<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp.html<br />
<br />
https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/<br />
<br />
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-smtp-software-package.html<br />
<br />
Or if you want to install your own SMTP server:<br />
<br />
https://ubuntu.com/server/docs/mail-postfix<br />
<br />
Then save the file and Quit.<br />
<br />
'''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.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://webwork.yourschool.edu/webwork2</code> (or <code>http://18.190.3.215/webwork2</code> if your haven't set up a URL yet) where of course you should use your actual URL or ip address.<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Set up WeBWorK to use SSL==<br />
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. <br />
<br />
You can find general directions in [[Installation_Manual_for_2.18_on_Ubuntu#Implement_Option_A_.28SSL.29 | Set up SSL in the Installation Manual for 2.18 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.<br />
<br />
<br />
Here we will give explicit directions for working with your AWS instance, Google Domains and Let's Encrypt. Working with other setups should be analogous.<br />
<br />
===First we set up our URL===<br />
Login to https://domains.google/ and select your domain or get a new one. As an example I will use my domain, "apizer.org". Select "apizer.org", click on "Manage", Select "DNS", "Custom records", "Manage custom records" and finally "Create a new record". For "Host name" enter "webwork" (which means the URL will be "webwork.apizer.org"), For "Type" select "A" meaning you are using ipv4, leave "TTL" at 3600 (1 hour) 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 | Give your Instance a permanent IP address]]. The click "Save"<br />
<br />
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.<br />
<br />
===Next we create our SLL certificate and key===<br />
<br />
First install certbot<br />
$ sudo snap install --classic certbot<br />
Next we need to stop the webwork2 app so that certbot can use port 80<br />
$ sudo systemctl stop webwork2<br />
Now run certbot<br />
$ sudo certbot certonly --standalone<br />
When it requests "Please enter the domain name(s) you would like on your certificate (comma and/or<br />
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:<br />
/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem<br />
/etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
Finally make sure that these files are readable by the webwork2 app:<br />
$ sudo chown www-data /etc/letsencrypt/live/webwork.apizer.org/fullchain.pem /etc/letsencrypt/live/webwork.apizer.org/privkey.pem<br />
<br />
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<br />
/etc/letsencrypt/archive/<br />
since the files under <code>.../live/</code> are links pointing to files under <code>.../archive/</code><br />
In my case certbot created directories that are all world executable, e.g.<br />
ls -l /etc/letsencrypt/<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 archive<br />
drwxr-xr-x 4 root root 4096 Aug 30 18:59 live<br />
so there was no problem but several others have reported that was not the case when they ran certbot. If you have problems, this is something to check.<br />
<br />
===Now we we configure the webwork2 app to use SSL===<br />
====Edit webwork2.mojolicious.yml====<br />
We need to tell hypnotoad where the certificates are. First we make a backup of the <code>webwork2.mojolicious.yml</code> file and then edit it:<br />
$ su wwadmin<br />
<br />
$ cp webwork2.mojolicious.yml webwork2.mojolicious.yml.bak1<br />
$ nano webwork2.mojolicious.yml<br />
<br />
In the <code>hypnotoad:</code> section below the lines<br />
<br />
listen:<br />
- <nowiki>http://*:80</nowiki><br />
add the line<br />
- <nowiki>https://*:443?cert=/etc/letsencrypt/live/webwork.apizer.org/fullchain.pem&key=/etc/letsencrypt/live/webwork.apizer.org/privkey.pem</nowiki><br />
where of course use the path to your certificate and key. <br />
<br />
Finally a few lines above this change<br />
redirect_http_to_https: 0<br />
to<br />
redirect_http_to_https: 1<br />
<br />
Then save the file and quit.<br />
<br />
====Edit site.conf====<br />
<br />
Now backup and then edit site.conf<br />
cp site.conf site.conf.bak2<br />
nano site.conf<br />
<br />
The <code>$server_root_url</code> is set as<br />
$server_root_url = '<nowiki>http://18.190.3.215/</nowiki>';<br />
where of course <code>18.190.3.215</code> is replaced by your actual ip address. Change this to<br />
$server_root_url = '<nowiki>https://webwork.apizer.org/</nowiki>';<br />
where of course use your own URL obtained above and don't forget to enter https in place of http.<br />
<br />
The save the file and quit.<br />
<br />
====Start the webwork2 app====<br />
Stop acting as wwadmin and then start the webwork2 app:<br />
$ exit<br />
$ sudo systemctl start webwork2<br />
<br />
====Test that all is well====<br />
<br />
Try accessing your server using your new URL. E.g. accessing your server using either "<nowiki>http://webwork.apizer.org/webwork2</nowiki>" or "<nowiki>https://webwork.apizer.org/webwork2</nowiki>" (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.<br />
<br />
==Finish up==<br />
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.<br />
<br />
==Passwords==<br />
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.<br />
Also it is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the MariaDB user webworkWrite who has login privileges to MariaDB. Otherwise anyone can connect to MariaDB 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. Finally you need to change the mojolicious secret<br />
<br />
====Change the mojolicious secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
<br />
====Change the password for wwadmin====<br />
$su wwadmin<br />
Password: wwadmin<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$exit<br />
exit<br />
$ <br />
'''Do not forget the <code>&lt;new wwadmin password&gt;</code> 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.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$su wwadmin<br />
Password: <wwadmin password><br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = 'wwadmin';</code> and replace this by <br /> <code>$database_password = 'database_password';</code> <br />
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 <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart the webwork2 app so the changes take effect.<br />
$ exit<br />
exit<br />
$ sudo systemctl restart webwork2<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <br />
You should see that the user <code>webworkWrite</code>) has a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT user,password,authentication_string,plugin,host FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDBl><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
Change the passwords for the WeBWorK user admin in two courses. Login to both the WeBWorK admin course (<nowiki>http://.../webwork2/admin</nowiki>) and myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for profa====<br />
Change the passwords for the WeBWorK user profa. Login to myTestCourse (<nowiki>http://.../webwork2/myTestCourse</nowiki>) 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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
<nowiki>http://webwork.yourschool.edu/webwork2/admin</nowiki> <br />
<nowiki>http://webwork.yourschool.edu/webwork2/mytestcourse</nowiki> <br />
where of course you should use your actual URL.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Hypnotoad's configuration according to your server's memory===<br />
Look at [[Installation_Manual_for_2.18_on_Ubuntu#Option_1:_Serving_Directly_via_Hypnotoad|Serving Directly via Hypnotoad in the Installation Manual for 2.18 on Ubuntu 22.04 Server]] and adjust "clients", "workers" and "spare" in the file <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> according to the rule of thumb given there.<br />
<br />
===Changing the instance type===<br />
<br />
For general information look at the following reference and also google "change the instance type of ec2"<br />
* https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html#resize-ebs-backed-instance<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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. <br />
<br />
# In the navigation pane, choose Instances.<br />
# Select the instance and choose Actions, Instance State, Stop.<br />
# In the confirmation dialog box, choose Yes, Stop. It can take a few minutes for the instance to stop.<br />
# With the instance still selected, choose Actions, Instance Settings, Change Instance Type. This action is disabled if the instance state is not stopped.<br />
# In the Change Instance Type dialog box, do the following:<br />
# From Instance Type, select the instance type that you want.<br />
# (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.<br />
# Choose Apply to accept the new settings.<br />
# To restart the stopped instance, select the instance and choose Actions, Instance State, Start.<br />
<br />
Remember to [[#Adjust Hypnotoad's configuration according to your server's memory | Adjust Hypnotoad's configuration according to your server's memory]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is<br />
====Expand the EBS root volume====<br />
For general information look at the following reference and also google "expand disk of ec2"<br />
* https://aws.amazon.com/premiumsupport/knowledge-center/expand-root-ebs-linux/<br />
<br />
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 <br />
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".<br />
You will see<br />
Modify Volume Request Succeeded<br />
Your volume is now being modified.<br />
<br />
<br />
The second step is to<br />
<br />
====Repartition the disk and expand the file system====<br />
Let us assume you have completed the first step and expanded the disk capacity from it's initial<br />
20 GB to 25GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
<br />
/dev/root 20G 5.3G 15G 28% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
<br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/xvda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 21.5GB 21.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
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<br />
(parted) resizepart<br />
Partition number? 1<br />
Warning: Partition /dev/xvda1 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [21.5GB]? 26.5GB<br />
(parted)<br />
<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: Xen Virtual Block Device (xvd)<br />
Disk /dev/xvda: 26.8GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: msdos<br />
Disk Flags:<br />
<br />
Number Start End Size Type File system Flags<br />
1 1049kB 26.5GB 26.5GB primary ext4 boot<br />
<br />
(parted)<br />
<br />
Notice we now have a 26.5 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
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<br />
$ sudo resize2fs /dev/xvda1 <br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/xvda1 is mounted on /; on-line resizing required<br />
old_desc_blocks = 3, new_desc_blocks = 4<br />
The filesystem on /dev/xvda1 is now 6469470 (4k) blocks long.<br />
<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
/dev/root 24G 5.3G 19G 23% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]] [[Category:Amazon Machine Images]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Virtual_Machine_Image&diff=24177WeBWorK 2.18 Ubuntu Server 22.04 LTS Virtual Machine Image2023-09-11T18:08:54Z<p>Apizer: /* Import the .ova file */</p>
<hr />
<div><!--<br />
{{UnderConstruction}} <br />
--><br />
<br />
These instructions cover the installation of the Ubuntu Server 22.04 LTS 64 bit operating system and WeBWorK 2.18 using the WeBWorK Virtual Machine Image. <br />
<br />
The WeBWorK Virtual Machine Image is an <code>.ova</code> file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, QEMU/KVM, etc. <br />
<br />
This image file has been tested on <br />
* VMware Workstation 17 Player<br />
* VirtualBox 7<br />
* QEMU/KVM running on a Ubuntu 22.04 Desktop host<br />
<br />
This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc.) installed and configured. <br />
<br />
== Installing from WW2.18 Ubuntu22.04 Server Virtual Machine Image ==<br />
<br />
===Overview===<br />
After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who has sudo privileges), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> who has professor privileges and also the Mjolicious secret (see below).<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]].<br />
<br />
===Download the ova image===<br />
<br />
Download the sha256 checksum and the .ova files from the WeBWorK Download Site below. <br />
<br />
You want to download the files <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code> and <code>WW2.18_Ubuntu22.04_Server.ova</code><br />
The ova is a 7.3 GB file.<br />
<br />
* [http://webwork.maa.org/ww-downloads/wwdownload.html WeBWorK Download Site]<br />
<br />
Verify the SHA256 checksum of your downloaded file <code>WW2.18_Ubuntu22.04_Server.ova</code> agrees with the one in <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code>.<br />
<br />
===OVA and OVF files===<br />
The <code>.ova</code> file is simply a tar bundle containing an <code>.ovf</code> file, one or more <code>.vmdk</code> files, a <code>.mf</code> file and possibly other files.<br />
* The <code>.ovf</code> file is an XML file which describes the packaged virtual machine and is human-readable. <br />
* The <code>.vmdk</code> file(s) contain the disk images(s).<br />
* Possibly other files<br />
* The <code>.mf</code> file contains SHA1 checksums for the above files.<br />
<br />
You can import a virtual machine either from an <code>.ova</code> file or from the <code>.ovf</code>, <code>.vmdk</code>, <code>.mf</code> collection. Sometimes importing from the <code>.ova</code> file may fail whereas importing from the <code>.ovf</code> or <code>.vmdk</code> file will succeed.<br />
<br />
You can extract the files in <code>WW2.18_Ubuntu22.04_Server.ova</code> with the command <br />
<br />
$ tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
<br />
You then can look at (and possibly edit) the human readable <code>WW2.18_Ubuntu22.04_Server.ofv</code> file. If you do edit the <code>WW2.18_Ubuntu22.04_Server.ofv</code> file, you will also have to compute the new SHA1 checksum and replace the old one in the <code>WW2.18_Ubuntu22.04_Server.mf</code> file for the files to be usable.<br />
<br />
===Installing the WeBWorK Virtual Machine Image ===<br />
<br />
Import the file <code>WW2.18_Ubuntu22.04_Server.ova</code> into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 17 Player <br />
running on a Windows 11 Pro host. It has been tested on <br />
* VMware Workstation 17 Player running on a Windows 11 host (Pro edition)<br />
* VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host<br />
* VirtualBox 7 running on a Windows 11 host (Home and Pro editions)<br />
* VirtualBox 7 running on a Ubuntu 22.04 Desktop host<br />
* QEMU/KVM running on a Ubuntu 22.04 Desktop host<br />
'''See [[#Specific Virtual Environments|Specific Virtual Environments]] below for installation information on specific virtual environments.'''<br />
<br />
====Processors, Memory, Hard Disk, Networking====<br />
The WeBWorK Virtual Machine Image was created with the following parameters:<br />
*20 GB dynamically allocated disk drive in VMDK format (single file) of which 13 GB is used<br />
*4 GB memory<br />
*2 cpu<br />
These resources are OK for testing and may suffice for a very small course but it is possible to overwhelm the machine. <br />
<br />
Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 17 Player running on a Windows 11 host). You should adjust these resources either when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk is more complicated. See [[#Specific Virtual Environments|Specific Virtual Environments]] below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see [[#Increase Disk Space|Increase Disk Space]] below). <br />
<br />
Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]) and/or look at [[#Debugging Networking Issues|Debugging Networking Issues]].<br />
<br />
===Import the .ova file===<br />
There may be specific information for your situation below. See<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 7 running on a Ubuntu 22.04 Desktop host|VirtualBox 7 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
* [[#Amazon EC2|Amazon EC2]]<br />
<br />
===Your server===<br />
After importing, your virtual WeBWorK server will be identical to a system created by following the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] with the Webwork2 Mojolicious App being served directly via hypnotoad (option 1) and the Optional Configurations B and C implemented. '''Note that''' Option A (SSL) is not implemented (see [[#Set up WeBWorK to use SSL|Set up WeBWorK to use SSL]] below).<br />
<br />
'''Note''' that on some virtual environments, you may need to take additional actions. See the section [[#Specific Virtual Environments|Specific Virtual Environments]] below.<br />
<br />
You should read through the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] in order to understand how your server has been set up. Especially look at<br />
[[Installation Manual for 2.18 on Ubuntu#Notation|Notation in the Installation Manual for 2.18 on Ubuntu]] to understand the notation we use in these instructions.<br />
<br />
==Boot Your Server==<br />
===Log into your server ===<br />
After booting you should see a login prompt (you may have to press <code>&lt;Enter&gt;</code>).<br />
*Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges. We will denote<br />
wwadmin's password by <code><wwadmin password></code>. Initially this is set to <code>wwadmin</code>.<br />
If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.<br />
<br />
===Test your ip address===<br />
Run the command<br />
$ ip address show<br />
and look at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]). If that doesn't help look at [[#Debugging Networking Issues|Debugging Networking Issues]]. '''You have to fix this before you can go on to the next step'''.<br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program. <br />
<br />
You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with <code>copy</code> from the Edit menu or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit menu list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code> or <code>&lt;Shift&gt; &lt;Insert&gt;</code> depending on your application). <br />
<br />
My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. In any event, after testing, read the section [[#Make the WeBWorK Configuration Permanent|Make the WeBWorK Configuration Permanent]] below. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.<br />
<br />
I am assuming your network has been set up automatically.<br />
<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a <br />
terminal emulator running on your host using ssh, or from the terminal on the guest once you login. <br />
<br />
Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will probably see <br />
...<br />
Time zone: Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/New_York". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/New_York<br />
[sudo] password for wwadmin: <wwadmin password><br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
=== Checking for and Installing Hotfixes ===<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check_for_and_Install_Hotfixes in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
'''Important: The are bug fixes for both the webwork2 code and the pg code that occurred after the virtual machine image was built. You should definitely update both the webwork2 and pg code.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the virtual machine image was built. <br />
You should definitely update the webwork2 code.'''<br />
--><br />
<!--<br />
'''Important: The are bug fixes for the pg code that occurred after the virtual machine image was built. You should definitely update the pg code.'''<br />
--><br />
<br />
=== WeBWorK configuration ===<br />
<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
First we have to edit information about the network server setup. <br />
Search for <code>192.168.138.131</code> and replace that by your the new ip address you found above (<code>192.168.76.128</code> in our example above). <br />
<br />
'''But wait, this can be tricky'''. If you set up port forwarding (as we had to for VirtualBox), then instead use the code<br />
$server_root_url = 'http://localhost';<br />
<br />
The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM)<br />
<br />
$server_root_url = 'http://192.168.76.128';<br />
<br />
where of course your ip address may be different. The "http://" is important. <br />
<br />
'''Remark'''. First of all, let me admit I don't understand the above - it just works. If this is not set correctly (and I don't really understand what "correctly" means), then when you test the Library Browser, e.g. by clicking on <code>Library Browser</code> on the <code>Main Menu</code>, then on <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, you will not be able to select a <code>Chapter</code> and you will see an error message similar to<br />
183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.<br />
If you google this message, you will find a lot of people have seen this error and the most common reason is that <code>$server_root_url</code> has not been set correctly, whatever "correctly" means. A common error is to forget <code>http://</code> or to use <code>http://</code> when you should use <code>https://</code> (or vice versa) or to just have the wrong domain name or ip address.<br />
<br />
We now continue editing <code>site.conf</code> <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then.<br />
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.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.'''<br />
<br />
Then save the file and Quit. And restart the webwork2 app so that these changes take effect:<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
===Set up WeBWorK to use SSL===<br />
This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.<br />
<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Implement Option A (SSL)|Implement Option A (SSL) in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
Note that the Virtual Machine Image was built using Option 1: Serving Directly via Hypnotoad so that in the instructions for setting up SSL follow the section<br />
Set up Hypnotoad to use SSL (Option 1).<br />
<br />
===Finish up===<br />
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.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://192.168.76.128/webwork2</code> where of course you should use your actual ip address. If you have already set up https and haven't setup the redirect, then you should use <code>https://192.168.76.128/webwork2</code> . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.<br />
<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Make the WeBWorK Configuration Permanent==<br />
<br />
Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with <code>ip address show</code>) and used that when editing the <code>site.conf</code> file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.<br />
# The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the <code>site.conf</code> file. <br />
# The other method is to setup networking to use a fixed specific ip address for your server and use that in the <code>site.conf</code> file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the [[#Networking_2|Networking]] section under [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] below for information on editing these files. You can search the web for information on the correct syntax to use.<br />
<br />
Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections [[#Edit the site.conf file|Edit the site.conf file]] and [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]].<br />
<br />
Remember that any time you edit WeBWorK's configuration files, you have the restart the WeBWorK2 app for the changes to take effect; see [[Installation_Manual_for_2.18_on_Ubuntu#Enable_and_start_the_Webwork2_Systemd_Service|Enable_and_start_the_Webwork2_Systemd_Service in the Installation Manual for 2.18 on Ubuntu]]. For networking changes to take effect, you should reboot the server.<br />
<br />
==Passwords==<br />
It is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access.<br />
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. Also change the mojolicious.yml secret.<br />
====Change the mojolicious.yml secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
====Change the password for wwadmin====<br />
<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$ <br />
'''Do not forget the new <code>&lt;wwadmin password&gt;</code> that you just entered.''' Below when we refer to <wwadmin password>, we mean the '''new''' <wwadmin password>.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = "wwadmin";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. We refer to this password as <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart webwork2 so the changes take effect.<br />
<br />
$ sudo systemctl restart webwork2<br />
[sudo] password for wwadmin: <wwadmin password><br />
$<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,authentication_string,password,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <code>webworkWrite</code> should have <br />
a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT Host, User, password FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
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.<br />
<br />
====Change the password for profa====<br />
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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
http://192.168.76.128/webwork2/admin</code> <br />
http://192.168.76.128/webwork2/mytestcourse</code> <br />
where of course you should use your actual ip address.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust the mojolicious.yml configuration according to your server's memory===<br />
Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. <br />
Search for the lines<br />
clients: 1<br />
workers: 10<br />
spare: 5<br />
and edit the numbers depending on the amount of RAM available on your server. Look at the recommendations for these settings in the section immediately above these lines in the webwork2.mojolicious.yml file<br />
<br />
Then save the file and Quit.<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in [[#Specific Virtual Environments|Specific Virtual Environments]] below. <br />
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<br />
20 GB to 30GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 19G 11G 7.3G 59% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/sda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 21.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags: <br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 20.0GB 20.0GB ext4<br />
<br />
(parted)<br />
<br />
We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command<br />
(parted) resizepart<br />
Partition number? 2<br />
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [20GB]? 30GB<br />
(parted)<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 31.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags:<br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 30.0GB 30.0GB ext4<br />
<br />
(parted)<br />
Notice we now have a 30 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below<br />
$ sudo resize2fs /dev/sda2<br />
[sudo] password for wwadmin: <wwadmin password><br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/sda2 is mounted on /; on-line resizing required<br />
old_desc_blocks = 2, new_desc_blocks = 3<br />
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 29G 11G 18G 38% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
*'''Option A''' is not implemented. '''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
==Specific Virtual Environments==<br />
Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of<br />
the specific environments we have information on:<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 15 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
<br />
===VMware Workstation 17 Player running on a Windows 11 host===<br />
====Importing the ova File====<br />
For VMware Player select Player, File, Open and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file.<br />
Name your machine and select a storage path and then hit Import<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
====Accessing your server from your host====<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the '''WeBWorK Placeholder Page'''. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the '''WeBWorK''' Welcome page. <br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 17 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Windows 11 host===<br />
<br />
====Importing the ova File====<br />
For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file. Click Finish. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Initially networking will be broken. Do the following from your guest WeBWorK system<br />
$ sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
...<br />
logical name: enp0s17<br />
version: 02<br />
serial: 08:00:27:30:28:b6<br />
...<br />
Remember the logical name from your system as we will need it below. We have to backup and then edit one file.<br />
<br />
$ cd /etc/netplan/<br />
$ sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak1<br />
[sudo] password for wwadmin: <wwadmin password> <br />
Now edit the <code> 00-installer-config.yaml</code> file<br />
$ sudo nano 00-installer-config.yaml<br />
It should look like (I had to stretch the window to see the whole file):<br />
# This is the network config written by 'subiquity'<br />
network:<br />
ethernets:<br />
ens33:<br />
dhcp4: true<br />
version: 2<br />
Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.<br />
<br />
<br />
Now reboot your server,e.g.<br />
$ sudo reboot<br />
[sudo] password for wwadmin: <wwadmin password> <br />
login and run the command<br />
$ ip address show<br />
and look at the output, something like<br />
... <br />
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000<br />
link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff<br />
inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17<br />
...<br />
<br />
We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below. <br />
<br />
In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network"<br />
Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:<br />
<br />
{| class="wikitable"<br />
|+Port Forwarding<br />
!Name<br />
!Protocol<br />
!Host IP<br />
!Host Port<br />
!Guest IP<br />
!Guest Port<br />
|-<br />
|ssh<br />
|TCP<br />
|127.0.0.1<br />
|2222<br />
|10.0.2.15<br />
|22<br />
|-<br />
|https<br />
|TCP<br />
|127.0.0.1<br />
|4443<br />
|10.0.2.15<br />
|443<br />
|-<br />
|http<br />
|TCP<br />
|127.0.0.1<br />
|8081<br />
|10.0.2.15<br />
|80<br />
|}<br />
Double check that you have entered everything correctly ('''using''' your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".<br />
<br />
Now boot your server.<br />
<br />
====Accessing your server from your host====<br />
We need to employ the port forwarding rules above.<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up with the port forwarding rules above, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and you should the '''WeBWorK''' Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.<br />
<br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your guest is shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list <br />
(probably "WW2.18_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. <br />
Click “Apply” when you're done.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host===<br />
<br />
====Importing the ova File====<br />
For VMware Player select File, Open a Virtual Machine and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and import the file.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
Accessing your server is exactly the same as in [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]] above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.76.128<br />
where of course you need to use the ip address of your WeBWorK guest server.<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Ubuntu 22.04 Desktop host===<br />
====Importing the ova File====<br />
Importing the ova File is exactly the same as in [[#VirtualBox 76 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card)<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
# Set up port forwarding<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details.<br />
<br />
'''Except''' that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh -p 2222 wwadmin@127.0.0.1<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
The procedure is the same as in [[#Expand the disk drive_2|Expand the disk drive]] the Windows 11 case above.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===QEMU/KVM running on a Ubuntu 22.04 Desktop host===<br />
====First install Qemu-KVM====<br />
<br />
It is probably a good idea to first update and upgrade the system packages:<br />
$ sudo apt update<br />
$ sudo apt upgrade<br />
<br />
Now install Qemu-KVM<br />
$ sudo apt install -y qemu-kvm virt-manager libvirt-daemon-system virtinst libvirt-clients bridge-utils<br />
<br />
Enable and start libvirtd<br />
$ sudo systemctl enable --now libvirtd<br />
$ sudo systemctl start libvirtd<br />
and check that all is OK<br />
$ sudo systemctl status libvirtd<br />
<br />
Now add wwadmin to the kvm and libvirt groups.<br />
$ sudo usermod -aG kvm $USER<br />
$ sudo usermod -aG libvirt $USER<br />
<br />
====Convert the image to qcow2 format====<br />
<br />
cd to whatever directory you downloaded the <code>WW2.18_Ubuntu22.04_Server.ova</code> file to (maybe "Downloads") and then untar it<br />
tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
which might take awhile. Then run the command to covert the vmdk format to qcow2 format<br />
qemu-img convert -p -f vmdk -O qcow2 WW2.18_Ubuntu22.04_Server-disk1.vmdk WW2.18_Ubuntu22.04_Server.qcow2<br />
and move the qcow2 image to the correct location<br />
sudo mv WW2.18_Ubuntu22.04_Server.qcow2 /var/lib/libvirt/images/<br />
<br />
====Boot up your virtual machine====<br />
Start up Virtual Machine Manager (search for VM in the app manager). Note that if you run into problems running the Virtual Machine Manager (e.g. QEMU/KVM not connected), the first thing to try is rebooting your host machine.<br />
<br />
In the Virtual Machine Manager,<br />
select File, New Virtual Machine, Import existing disk image, Forward, Browse and finally select WW2.18_Ubuntu22.04_Server.qcow2. The select Choose Volume and enter Ubuntu 22.04 LTS for the operating system you are installing. Next click Forward and choose your memory and CPUs. Select Forward again, name your system and finally select finish.<br />
<br />
Now log into your virtual machine (wwadmin with password wwadmin)<br />
<br />
====Networking====<br />
<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card), probably something like enp1s0<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details '''except that'''<br />
# You do not need port forwarding<br />
# Instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.122.233<br />
(where of course you need to use the actual ip address of your guest WeBWorK server).<br />
<br />
====Expand the disk drive====<br />
You can do most of this from the graphical Virtual Machine Manager (select the machine, then Edit, Virtual Machine Details). Below are commands to this from the command line. I think you have to actually expand the disk from the command line but you can get information and add cpu's and/or memory from the graphical Virtual Machine Manager.<br />
<br />
I'm assume the name of your WeBWorK guest is <code>wwserver</code> and it is Shutoff. First find the location of the disk.<br />
Run the command<br />
$ sudo virsh domblklist wwserver<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
Target Source<br />
-------------------------------------------------------------------------<br />
sda /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
<br />
Now get some info about the disk<br />
$ sudo qemu-img info /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
image: /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
file format: qcow2<br />
virtual size: 12 GiB (12884901888 bytes)<br />
disk size: 6.76 GiB<br />
cluster_size: 65536<br />
Format specific information:<br />
compat: 1.1<br />
lazy refcounts: false<br />
refcount bits: 16<br />
corrupt: false<br />
<br />
and now lets resize it to 20 GB by adding 8 GB<br />
sudo qemu-img resize /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2 +8G<br />
[sudo] password for wwadmin: <wwadmin password><br />
Image resized.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===Amazon EC2===<br />
While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the [[WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image]] is faster and easier anyway.<br />
<br />
==Debugging Networking Issues==<br />
If after reading the information above on networking you are still having problems, maybe the information below will be of help.<br />
<br />
===One method===<br />
There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms:<br />
$ ip address show<br />
does not return an ip address and the WW guest can not access the outside world.<br />
<br />
In VirtualBox I built another guest from the <code>ubuntu-22.04-live-server-amd64.iso</code> using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by<br />
sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files<br />
/etc/netplan/00-installer-config.yaml<br />
and<br />
/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg<br />
BUT in the WW guest the information did not agree. This led to the information given in [[#Networking_2|the Networking section of VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
===Ports on your WeBWorK guest===<br />
Run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you see something like<br />
<br />
systemd-r 697 systemd-resolve 13u IPv4 19596 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
sshd 772 root 3u IPv4 21834 0t0 TCP *:22 (LISTEN)<br />
sshd 772 root 4u IPv6 21845 0t0 TCP *:22 (LISTEN)<br />
lighttpd 810 www-data 4u IPv4 22509 0t0 TCP *:8080 (LISTEN)<br />
mysqld 856 mysql 31u IPv6 23312 0t0 TCP *:33060 (LISTEN)<br />
mysqld 856 mysql 33u IPv4 23654 0t0 TCP 127.0.0.1:3306 (LISTEN)<br />
Rserve 865 rserveuser 3u IPv4 22878 0t0 TCP 127.0.0.1:6311 (LISTEN)<br />
/usr/sbin 946 root 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 956 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 957 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 958 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 959 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 960 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
<br />
===Ports on your Windows 11 Pro host===<br />
Open a Power Shell command window as an administrator and run the command (it can take awhile)<br />
PS C:\> netstat -ab<br />
<br />
Active Connections<br />
<br />
Proto Local Address Foreign Address State<br />
TCP 0.0.0.0:135 desktop:0 LISTENING<br />
RpcSs<br />
[svchost.exe]<br />
TCP 0.0.0.0:443 desktop:0 LISTENING<br />
[vmware-hostd.exe]<br />
TCP 0.0.0.0:445 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:903 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:913 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:2869 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:3306 desktop:0 LISTENING<br />
[mysqld.exe]<br />
...<br />
TCP 0.0.0.0:6000 desktop:0 LISTENING<br />
[XWin_MobaX.exe]<br />
TCP 0.0.0.0:49664 desktop:0 LISTENING<br />
...<br />
TCP 127.0.0.1:2222 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52916 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52917 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:4443 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
...<br />
<br />
===Ports on your Linux host===<br />
<br />
Run the command<br />
<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for ****: <br />
<br />
and you should see something like the following<br />
systemd-r 436 systemd-resolve 13u IPv4 18620 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
vmware-au 1284 root 10u IPv6 33012 0t0 TCP *:902 (LISTEN)<br />
vmware-au 1284 root 11u IPv4 33013 0t0 TCP *:902 (LISTEN)<br />
sshd 8786 root 3u IPv4 114131 0t0 TCP *:22 (LISTEN)<br />
sshd 8786 root 4u IPv6 114133 0t0 TCP *:22 (LISTEN)<br />
cupsd 12124 root 6u IPv6 138503 0t0 TCP [::1]:631 (LISTEN)<br />
cupsd 12124 root 7u IPv4 138504 0t0 TCP 127.0.0.1:631 (LISTEN)<br />
VirtualBo 17065 wwadmin 48u IPv4 185297 0t0 TCP 127.0.0.1:8081 (LISTEN)<br />
VirtualBo 17065 wwadmin 49u IPv4 185298 0t0 TCP 127.0.0.1:4443 (LISTEN)<br />
VirtualBo 17065 wwadmin 50u IPv4 185299 0t0 TCP 127.0.0.1:8080 (LISTEN)<br />
VirtualBo 17065 wwadmin 51u IPv4 185300 0t0 TCP 127.0.0.1:2222 (LISTEN)<br />
<br />
Notice that port forwarding for VirtualBox has been set up correctly.<br />
<br />
<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Virtual_Machine_Image&diff=24176WeBWorK 2.18 Ubuntu Server 22.04 LTS Virtual Machine Image2023-09-11T18:07:58Z<p>Apizer: /* Installing the WeBWorK Virtual Machine Image */</p>
<hr />
<div><!--<br />
{{UnderConstruction}} <br />
--><br />
<br />
These instructions cover the installation of the Ubuntu Server 22.04 LTS 64 bit operating system and WeBWorK 2.18 using the WeBWorK Virtual Machine Image. <br />
<br />
The WeBWorK Virtual Machine Image is an <code>.ova</code> file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, QEMU/KVM, etc. <br />
<br />
This image file has been tested on <br />
* VMware Workstation 17 Player<br />
* VirtualBox 7<br />
* QEMU/KVM running on a Ubuntu 22.04 Desktop host<br />
<br />
This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc.) installed and configured. <br />
<br />
== Installing from WW2.18 Ubuntu22.04 Server Virtual Machine Image ==<br />
<br />
===Overview===<br />
After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who has sudo privileges), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> who has professor privileges and also the Mjolicious secret (see below).<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]].<br />
<br />
===Download the ova image===<br />
<br />
Download the sha256 checksum and the .ova files from the WeBWorK Download Site below. <br />
<br />
You want to download the files <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code> and <code>WW2.18_Ubuntu22.04_Server.ova</code><br />
The ova is a 7.3 GB file.<br />
<br />
* [http://webwork.maa.org/ww-downloads/wwdownload.html WeBWorK Download Site]<br />
<br />
Verify the SHA256 checksum of your downloaded file <code>WW2.18_Ubuntu22.04_Server.ova</code> agrees with the one in <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code>.<br />
<br />
===OVA and OVF files===<br />
The <code>.ova</code> file is simply a tar bundle containing an <code>.ovf</code> file, one or more <code>.vmdk</code> files, a <code>.mf</code> file and possibly other files.<br />
* The <code>.ovf</code> file is an XML file which describes the packaged virtual machine and is human-readable. <br />
* The <code>.vmdk</code> file(s) contain the disk images(s).<br />
* Possibly other files<br />
* The <code>.mf</code> file contains SHA1 checksums for the above files.<br />
<br />
You can import a virtual machine either from an <code>.ova</code> file or from the <code>.ovf</code>, <code>.vmdk</code>, <code>.mf</code> collection. Sometimes importing from the <code>.ova</code> file may fail whereas importing from the <code>.ovf</code> or <code>.vmdk</code> file will succeed.<br />
<br />
You can extract the files in <code>WW2.18_Ubuntu22.04_Server.ova</code> with the command <br />
<br />
$ tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
<br />
You then can look at (and possibly edit) the human readable <code>WW2.18_Ubuntu22.04_Server.ofv</code> file. If you do edit the <code>WW2.18_Ubuntu22.04_Server.ofv</code> file, you will also have to compute the new SHA1 checksum and replace the old one in the <code>WW2.18_Ubuntu22.04_Server.mf</code> file for the files to be usable.<br />
<br />
===Installing the WeBWorK Virtual Machine Image ===<br />
<br />
Import the file <code>WW2.18_Ubuntu22.04_Server.ova</code> into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 17 Player <br />
running on a Windows 11 Pro host. It has been tested on <br />
* VMware Workstation 17 Player running on a Windows 11 host (Pro edition)<br />
* VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host<br />
* VirtualBox 7 running on a Windows 11 host (Home and Pro editions)<br />
* VirtualBox 7 running on a Ubuntu 22.04 Desktop host<br />
* QEMU/KVM running on a Ubuntu 22.04 Desktop host<br />
'''See [[#Specific Virtual Environments|Specific Virtual Environments]] below for installation information on specific virtual environments.'''<br />
<br />
====Processors, Memory, Hard Disk, Networking====<br />
The WeBWorK Virtual Machine Image was created with the following parameters:<br />
*20 GB dynamically allocated disk drive in VMDK format (single file) of which 13 GB is used<br />
*4 GB memory<br />
*2 cpu<br />
These resources are OK for testing and may suffice for a very small course but it is possible to overwhelm the machine. <br />
<br />
Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 17 Player running on a Windows 11 host). You should adjust these resources either when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk is more complicated. See [[#Specific Virtual Environments|Specific Virtual Environments]] below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see [[#Increase Disk Space|Increase Disk Space]] below). <br />
<br />
Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]) and/or look at [[#Debugging Networking Issues|Debugging Networking Issues]].<br />
<br />
===Import the .ova file===<br />
There may be specific information for your situation below. See<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
* [[#Amazon EC2|Amazon EC2]]<br />
<br />
===Your server===<br />
After importing, your virtual WeBWorK server will be identical to a system created by following the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] with the Webwork2 Mojolicious App being served directly via hypnotoad (option 1) and the Optional Configurations B and C implemented. '''Note that''' Option A (SSL) is not implemented (see [[#Set up WeBWorK to use SSL|Set up WeBWorK to use SSL]] below).<br />
<br />
'''Note''' that on some virtual environments, you may need to take additional actions. See the section [[#Specific Virtual Environments|Specific Virtual Environments]] below.<br />
<br />
You should read through the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] in order to understand how your server has been set up. Especially look at<br />
[[Installation Manual for 2.18 on Ubuntu#Notation|Notation in the Installation Manual for 2.18 on Ubuntu]] to understand the notation we use in these instructions.<br />
<br />
==Boot Your Server==<br />
===Log into your server ===<br />
After booting you should see a login prompt (you may have to press <code>&lt;Enter&gt;</code>).<br />
*Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges. We will denote<br />
wwadmin's password by <code><wwadmin password></code>. Initially this is set to <code>wwadmin</code>.<br />
If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.<br />
<br />
===Test your ip address===<br />
Run the command<br />
$ ip address show<br />
and look at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]). If that doesn't help look at [[#Debugging Networking Issues|Debugging Networking Issues]]. '''You have to fix this before you can go on to the next step'''.<br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program. <br />
<br />
You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with <code>copy</code> from the Edit menu or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit menu list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code> or <code>&lt;Shift&gt; &lt;Insert&gt;</code> depending on your application). <br />
<br />
My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. In any event, after testing, read the section [[#Make the WeBWorK Configuration Permanent|Make the WeBWorK Configuration Permanent]] below. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.<br />
<br />
I am assuming your network has been set up automatically.<br />
<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a <br />
terminal emulator running on your host using ssh, or from the terminal on the guest once you login. <br />
<br />
Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will probably see <br />
...<br />
Time zone: Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/New_York". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/New_York<br />
[sudo] password for wwadmin: <wwadmin password><br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
=== Checking for and Installing Hotfixes ===<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check_for_and_Install_Hotfixes in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
'''Important: The are bug fixes for both the webwork2 code and the pg code that occurred after the virtual machine image was built. You should definitely update both the webwork2 and pg code.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the virtual machine image was built. <br />
You should definitely update the webwork2 code.'''<br />
--><br />
<!--<br />
'''Important: The are bug fixes for the pg code that occurred after the virtual machine image was built. You should definitely update the pg code.'''<br />
--><br />
<br />
=== WeBWorK configuration ===<br />
<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
First we have to edit information about the network server setup. <br />
Search for <code>192.168.138.131</code> and replace that by your the new ip address you found above (<code>192.168.76.128</code> in our example above). <br />
<br />
'''But wait, this can be tricky'''. If you set up port forwarding (as we had to for VirtualBox), then instead use the code<br />
$server_root_url = 'http://localhost';<br />
<br />
The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM)<br />
<br />
$server_root_url = 'http://192.168.76.128';<br />
<br />
where of course your ip address may be different. The "http://" is important. <br />
<br />
'''Remark'''. First of all, let me admit I don't understand the above - it just works. If this is not set correctly (and I don't really understand what "correctly" means), then when you test the Library Browser, e.g. by clicking on <code>Library Browser</code> on the <code>Main Menu</code>, then on <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, you will not be able to select a <code>Chapter</code> and you will see an error message similar to<br />
183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.<br />
If you google this message, you will find a lot of people have seen this error and the most common reason is that <code>$server_root_url</code> has not been set correctly, whatever "correctly" means. A common error is to forget <code>http://</code> or to use <code>http://</code> when you should use <code>https://</code> (or vice versa) or to just have the wrong domain name or ip address.<br />
<br />
We now continue editing <code>site.conf</code> <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then.<br />
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.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.'''<br />
<br />
Then save the file and Quit. And restart the webwork2 app so that these changes take effect:<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
===Set up WeBWorK to use SSL===<br />
This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.<br />
<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Implement Option A (SSL)|Implement Option A (SSL) in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
Note that the Virtual Machine Image was built using Option 1: Serving Directly via Hypnotoad so that in the instructions for setting up SSL follow the section<br />
Set up Hypnotoad to use SSL (Option 1).<br />
<br />
===Finish up===<br />
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.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://192.168.76.128/webwork2</code> where of course you should use your actual ip address. If you have already set up https and haven't setup the redirect, then you should use <code>https://192.168.76.128/webwork2</code> . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.<br />
<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Make the WeBWorK Configuration Permanent==<br />
<br />
Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with <code>ip address show</code>) and used that when editing the <code>site.conf</code> file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.<br />
# The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the <code>site.conf</code> file. <br />
# The other method is to setup networking to use a fixed specific ip address for your server and use that in the <code>site.conf</code> file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the [[#Networking_2|Networking]] section under [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] below for information on editing these files. You can search the web for information on the correct syntax to use.<br />
<br />
Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections [[#Edit the site.conf file|Edit the site.conf file]] and [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]].<br />
<br />
Remember that any time you edit WeBWorK's configuration files, you have the restart the WeBWorK2 app for the changes to take effect; see [[Installation_Manual_for_2.18_on_Ubuntu#Enable_and_start_the_Webwork2_Systemd_Service|Enable_and_start_the_Webwork2_Systemd_Service in the Installation Manual for 2.18 on Ubuntu]]. For networking changes to take effect, you should reboot the server.<br />
<br />
==Passwords==<br />
It is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access.<br />
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. Also change the mojolicious.yml secret.<br />
====Change the mojolicious.yml secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
====Change the password for wwadmin====<br />
<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$ <br />
'''Do not forget the new <code>&lt;wwadmin password&gt;</code> that you just entered.''' Below when we refer to <wwadmin password>, we mean the '''new''' <wwadmin password>.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = "wwadmin";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. We refer to this password as <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart webwork2 so the changes take effect.<br />
<br />
$ sudo systemctl restart webwork2<br />
[sudo] password for wwadmin: <wwadmin password><br />
$<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,authentication_string,password,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <code>webworkWrite</code> should have <br />
a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT Host, User, password FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
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.<br />
<br />
====Change the password for profa====<br />
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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
http://192.168.76.128/webwork2/admin</code> <br />
http://192.168.76.128/webwork2/mytestcourse</code> <br />
where of course you should use your actual ip address.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust the mojolicious.yml configuration according to your server's memory===<br />
Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. <br />
Search for the lines<br />
clients: 1<br />
workers: 10<br />
spare: 5<br />
and edit the numbers depending on the amount of RAM available on your server. Look at the recommendations for these settings in the section immediately above these lines in the webwork2.mojolicious.yml file<br />
<br />
Then save the file and Quit.<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in [[#Specific Virtual Environments|Specific Virtual Environments]] below. <br />
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<br />
20 GB to 30GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 19G 11G 7.3G 59% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/sda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 21.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags: <br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 20.0GB 20.0GB ext4<br />
<br />
(parted)<br />
<br />
We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command<br />
(parted) resizepart<br />
Partition number? 2<br />
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [20GB]? 30GB<br />
(parted)<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 31.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags:<br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 30.0GB 30.0GB ext4<br />
<br />
(parted)<br />
Notice we now have a 30 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below<br />
$ sudo resize2fs /dev/sda2<br />
[sudo] password for wwadmin: <wwadmin password><br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/sda2 is mounted on /; on-line resizing required<br />
old_desc_blocks = 2, new_desc_blocks = 3<br />
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 29G 11G 18G 38% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
*'''Option A''' is not implemented. '''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
==Specific Virtual Environments==<br />
Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of<br />
the specific environments we have information on:<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 15 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
<br />
===VMware Workstation 17 Player running on a Windows 11 host===<br />
====Importing the ova File====<br />
For VMware Player select Player, File, Open and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file.<br />
Name your machine and select a storage path and then hit Import<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
====Accessing your server from your host====<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the '''WeBWorK Placeholder Page'''. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the '''WeBWorK''' Welcome page. <br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 17 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Windows 11 host===<br />
<br />
====Importing the ova File====<br />
For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file. Click Finish. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Initially networking will be broken. Do the following from your guest WeBWorK system<br />
$ sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
...<br />
logical name: enp0s17<br />
version: 02<br />
serial: 08:00:27:30:28:b6<br />
...<br />
Remember the logical name from your system as we will need it below. We have to backup and then edit one file.<br />
<br />
$ cd /etc/netplan/<br />
$ sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak1<br />
[sudo] password for wwadmin: <wwadmin password> <br />
Now edit the <code> 00-installer-config.yaml</code> file<br />
$ sudo nano 00-installer-config.yaml<br />
It should look like (I had to stretch the window to see the whole file):<br />
# This is the network config written by 'subiquity'<br />
network:<br />
ethernets:<br />
ens33:<br />
dhcp4: true<br />
version: 2<br />
Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.<br />
<br />
<br />
Now reboot your server,e.g.<br />
$ sudo reboot<br />
[sudo] password for wwadmin: <wwadmin password> <br />
login and run the command<br />
$ ip address show<br />
and look at the output, something like<br />
... <br />
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000<br />
link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff<br />
inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17<br />
...<br />
<br />
We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below. <br />
<br />
In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network"<br />
Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:<br />
<br />
{| class="wikitable"<br />
|+Port Forwarding<br />
!Name<br />
!Protocol<br />
!Host IP<br />
!Host Port<br />
!Guest IP<br />
!Guest Port<br />
|-<br />
|ssh<br />
|TCP<br />
|127.0.0.1<br />
|2222<br />
|10.0.2.15<br />
|22<br />
|-<br />
|https<br />
|TCP<br />
|127.0.0.1<br />
|4443<br />
|10.0.2.15<br />
|443<br />
|-<br />
|http<br />
|TCP<br />
|127.0.0.1<br />
|8081<br />
|10.0.2.15<br />
|80<br />
|}<br />
Double check that you have entered everything correctly ('''using''' your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".<br />
<br />
Now boot your server.<br />
<br />
====Accessing your server from your host====<br />
We need to employ the port forwarding rules above.<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up with the port forwarding rules above, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and you should the '''WeBWorK''' Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.<br />
<br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your guest is shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list <br />
(probably "WW2.18_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. <br />
Click “Apply” when you're done.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host===<br />
<br />
====Importing the ova File====<br />
For VMware Player select File, Open a Virtual Machine and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and import the file.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
Accessing your server is exactly the same as in [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]] above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.76.128<br />
where of course you need to use the ip address of your WeBWorK guest server.<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Ubuntu 22.04 Desktop host===<br />
====Importing the ova File====<br />
Importing the ova File is exactly the same as in [[#VirtualBox 76 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card)<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
# Set up port forwarding<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details.<br />
<br />
'''Except''' that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh -p 2222 wwadmin@127.0.0.1<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
The procedure is the same as in [[#Expand the disk drive_2|Expand the disk drive]] the Windows 11 case above.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===QEMU/KVM running on a Ubuntu 22.04 Desktop host===<br />
====First install Qemu-KVM====<br />
<br />
It is probably a good idea to first update and upgrade the system packages:<br />
$ sudo apt update<br />
$ sudo apt upgrade<br />
<br />
Now install Qemu-KVM<br />
$ sudo apt install -y qemu-kvm virt-manager libvirt-daemon-system virtinst libvirt-clients bridge-utils<br />
<br />
Enable and start libvirtd<br />
$ sudo systemctl enable --now libvirtd<br />
$ sudo systemctl start libvirtd<br />
and check that all is OK<br />
$ sudo systemctl status libvirtd<br />
<br />
Now add wwadmin to the kvm and libvirt groups.<br />
$ sudo usermod -aG kvm $USER<br />
$ sudo usermod -aG libvirt $USER<br />
<br />
====Convert the image to qcow2 format====<br />
<br />
cd to whatever directory you downloaded the <code>WW2.18_Ubuntu22.04_Server.ova</code> file to (maybe "Downloads") and then untar it<br />
tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
which might take awhile. Then run the command to covert the vmdk format to qcow2 format<br />
qemu-img convert -p -f vmdk -O qcow2 WW2.18_Ubuntu22.04_Server-disk1.vmdk WW2.18_Ubuntu22.04_Server.qcow2<br />
and move the qcow2 image to the correct location<br />
sudo mv WW2.18_Ubuntu22.04_Server.qcow2 /var/lib/libvirt/images/<br />
<br />
====Boot up your virtual machine====<br />
Start up Virtual Machine Manager (search for VM in the app manager). Note that if you run into problems running the Virtual Machine Manager (e.g. QEMU/KVM not connected), the first thing to try is rebooting your host machine.<br />
<br />
In the Virtual Machine Manager,<br />
select File, New Virtual Machine, Import existing disk image, Forward, Browse and finally select WW2.18_Ubuntu22.04_Server.qcow2. The select Choose Volume and enter Ubuntu 22.04 LTS for the operating system you are installing. Next click Forward and choose your memory and CPUs. Select Forward again, name your system and finally select finish.<br />
<br />
Now log into your virtual machine (wwadmin with password wwadmin)<br />
<br />
====Networking====<br />
<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card), probably something like enp1s0<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details '''except that'''<br />
# You do not need port forwarding<br />
# Instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.122.233<br />
(where of course you need to use the actual ip address of your guest WeBWorK server).<br />
<br />
====Expand the disk drive====<br />
You can do most of this from the graphical Virtual Machine Manager (select the machine, then Edit, Virtual Machine Details). Below are commands to this from the command line. I think you have to actually expand the disk from the command line but you can get information and add cpu's and/or memory from the graphical Virtual Machine Manager.<br />
<br />
I'm assume the name of your WeBWorK guest is <code>wwserver</code> and it is Shutoff. First find the location of the disk.<br />
Run the command<br />
$ sudo virsh domblklist wwserver<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
Target Source<br />
-------------------------------------------------------------------------<br />
sda /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
<br />
Now get some info about the disk<br />
$ sudo qemu-img info /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
image: /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
file format: qcow2<br />
virtual size: 12 GiB (12884901888 bytes)<br />
disk size: 6.76 GiB<br />
cluster_size: 65536<br />
Format specific information:<br />
compat: 1.1<br />
lazy refcounts: false<br />
refcount bits: 16<br />
corrupt: false<br />
<br />
and now lets resize it to 20 GB by adding 8 GB<br />
sudo qemu-img resize /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2 +8G<br />
[sudo] password for wwadmin: <wwadmin password><br />
Image resized.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===Amazon EC2===<br />
While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the [[WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image]] is faster and easier anyway.<br />
<br />
==Debugging Networking Issues==<br />
If after reading the information above on networking you are still having problems, maybe the information below will be of help.<br />
<br />
===One method===<br />
There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms:<br />
$ ip address show<br />
does not return an ip address and the WW guest can not access the outside world.<br />
<br />
In VirtualBox I built another guest from the <code>ubuntu-22.04-live-server-amd64.iso</code> using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by<br />
sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files<br />
/etc/netplan/00-installer-config.yaml<br />
and<br />
/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg<br />
BUT in the WW guest the information did not agree. This led to the information given in [[#Networking_2|the Networking section of VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
===Ports on your WeBWorK guest===<br />
Run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you see something like<br />
<br />
systemd-r 697 systemd-resolve 13u IPv4 19596 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
sshd 772 root 3u IPv4 21834 0t0 TCP *:22 (LISTEN)<br />
sshd 772 root 4u IPv6 21845 0t0 TCP *:22 (LISTEN)<br />
lighttpd 810 www-data 4u IPv4 22509 0t0 TCP *:8080 (LISTEN)<br />
mysqld 856 mysql 31u IPv6 23312 0t0 TCP *:33060 (LISTEN)<br />
mysqld 856 mysql 33u IPv4 23654 0t0 TCP 127.0.0.1:3306 (LISTEN)<br />
Rserve 865 rserveuser 3u IPv4 22878 0t0 TCP 127.0.0.1:6311 (LISTEN)<br />
/usr/sbin 946 root 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 956 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 957 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 958 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 959 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 960 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
<br />
===Ports on your Windows 11 Pro host===<br />
Open a Power Shell command window as an administrator and run the command (it can take awhile)<br />
PS C:\> netstat -ab<br />
<br />
Active Connections<br />
<br />
Proto Local Address Foreign Address State<br />
TCP 0.0.0.0:135 desktop:0 LISTENING<br />
RpcSs<br />
[svchost.exe]<br />
TCP 0.0.0.0:443 desktop:0 LISTENING<br />
[vmware-hostd.exe]<br />
TCP 0.0.0.0:445 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:903 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:913 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:2869 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:3306 desktop:0 LISTENING<br />
[mysqld.exe]<br />
...<br />
TCP 0.0.0.0:6000 desktop:0 LISTENING<br />
[XWin_MobaX.exe]<br />
TCP 0.0.0.0:49664 desktop:0 LISTENING<br />
...<br />
TCP 127.0.0.1:2222 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52916 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52917 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:4443 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
...<br />
<br />
===Ports on your Linux host===<br />
<br />
Run the command<br />
<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for ****: <br />
<br />
and you should see something like the following<br />
systemd-r 436 systemd-resolve 13u IPv4 18620 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
vmware-au 1284 root 10u IPv6 33012 0t0 TCP *:902 (LISTEN)<br />
vmware-au 1284 root 11u IPv4 33013 0t0 TCP *:902 (LISTEN)<br />
sshd 8786 root 3u IPv4 114131 0t0 TCP *:22 (LISTEN)<br />
sshd 8786 root 4u IPv6 114133 0t0 TCP *:22 (LISTEN)<br />
cupsd 12124 root 6u IPv6 138503 0t0 TCP [::1]:631 (LISTEN)<br />
cupsd 12124 root 7u IPv4 138504 0t0 TCP 127.0.0.1:631 (LISTEN)<br />
VirtualBo 17065 wwadmin 48u IPv4 185297 0t0 TCP 127.0.0.1:8081 (LISTEN)<br />
VirtualBo 17065 wwadmin 49u IPv4 185298 0t0 TCP 127.0.0.1:4443 (LISTEN)<br />
VirtualBo 17065 wwadmin 50u IPv4 185299 0t0 TCP 127.0.0.1:8080 (LISTEN)<br />
VirtualBo 17065 wwadmin 51u IPv4 185300 0t0 TCP 127.0.0.1:2222 (LISTEN)<br />
<br />
Notice that port forwarding for VirtualBox has been set up correctly.<br />
<br />
<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.17_Ubuntu_Server_22.04_LTS_Virtual_Machine_Image&diff=24175WeBWorK 2.17 Ubuntu Server 22.04 LTS Virtual Machine Image2023-09-11T18:03:08Z<p>Apizer: Undo revision 24172 by Apizer (talk)</p>
<hr />
<div><!--<br />
{{UnderConstruction}} <br />
--><br />
<br />
These instructions cover the installation of the Ubuntu Server 22.04 LTS 64 bit operating system and WeBWorK 2.17 using the WeBWorK Virtual Machine Image. <br />
<br />
The WeBWorK Virtual Machine Image is an <code>.ova</code> file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, QEMU/KVM, etc. <br />
<br />
This image file has been tested on <br />
* VMware Workstation 16 Player<br />
* VirtualBox 6<br />
<br />
This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Apache2, MariaDB, R server, log rotation, etc.) installed and configured. <br />
<br />
== Installing from WW2.17 Ubuntu22.04 Server Virtual Machine Image ==<br />
<br />
===Overview===<br />
After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.17, Apache2, MariaDB, R server, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who has sudo privileges), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> who has professor privileges (see below).<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.17 at<br />
[[Installation_Manual_for_2.17_on_Ubuntu|Installation Manual for 2.17 on Ubuntu]].<br />
<br />
===Download the ova image===<br />
<br />
Download the .sha checksum and the .ova files from the WeBWorK Download Site below. <br />
<br />
You want to download the files <code>WW2.17_Ubuntu22.04_Server.ova.sha</code> and <code>WW2.17_Ubuntu22.04_Server.ova</code><br />
The ova is a 6.3 GB file.<br />
<br />
* [http://webwork.maa.org/ww-downloads/wwdownload.html WeBWorK Download Site]<br />
<br />
Verify the SHA1 checksum of your downloaded file <code>WW2.17_Ubuntu22.04_Server.ova</code> agrees with the one in <code>WW2.17_Ubuntu22.04_Server.ova.sha</code>.<br />
<br />
===OVA and OVF files===<br />
The <code>.ova</code> file is simply a tar bundle containing an <code>.ovf</code> file, one or more <code>.vmdk</code> files, a <code>.mf</code> file and possibly other files.<br />
* The <code>.ovf</code> file is an XML file which describes the packaged virtual machine and is human-readable. <br />
* The <code>.vmdk</code> file(s) contain the disk images(s).<br />
* Possibly other files<br />
* The <code>.mf</code> file contains SHA1 checksums for the above files.<br />
<br />
You can import a virtual machine either from an <code>.ova</code> file or from the <code>.ovf</code>, <code>.vmdk</code>, <code>.mf</code> collection. Sometimes importing from the <code>.ova</code> file may fail whereas importing from the <code>.ovf</code> or <code>.vmdk</code> file will succeed.<br />
<br />
You can extract the files in <code>WW2.17_Ubuntu22.04_Server.ova</code> with the command <br />
<br />
$ tar -xvf WW2.17_Ubuntu22.04_Server.ova<br />
<br />
You then can look at (and possibly edit) the human readable <code>WW2.17_Ubuntu22.04_Server.ofv</code> file. If you do edit the <code>WW2.17_Ubuntu22.04_Server.ofv</code> file, you will also have to compute the new SHA1 checksum and replace the old one in the <code>WW2.17_Ubuntu22.04_Server.mf</code> file for the files to be usable.<br />
<br />
===Installing the WeBWorK Virtual Machine Image ===<br />
<br />
Import the file <code>WW2.17_Ubuntu22.04_Server.ova</code> into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 16 Player <br />
running on a Windows 11 Pro host. It has been tested on <br />
* VMware Workstation 16 Player running on a Windows 11 host (Home and Pro editions)<br />
* VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host<br />
* VirtualBox 6 running on a Windows 11 host (Home and Pro editions)<br />
* VirtualBox 6 running on a Ubuntu 22.04 Desktop host<br />
'''See [[#Specific Virtual Environments|Specific Virtual Environments]] below for installation information on specific virtual environments.'''<br />
<br />
====Processors, Memory, Hard Disk, Networking====<br />
The WeBWorK Virtual Machine Image was created with the following parameters:<br />
*20 GB dynamically allocated disk drive in VMDK format (single file) of which 11 GB is used<br />
*4 GB memory<br />
*2 cpu<br />
These resources are OK for testing and should suffice for small courses but it is possible to overwhelm the machine.<br />
<br />
Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 16 Player running on a Windows 11 host). You should adjust these resources either when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk is more complicated. See [[#Specific Virtual Environments|Specific Virtual Environments]] below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see [[#Increase Disk Space|Increase Disk Space]] below). <br />
<br />
Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]) and/or look at [[#Debugging Networking Issues|Debugging Networking Issues]].<br />
<br />
===Import the .ova file===<br />
There may be specific information for your situation below. See<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
* [[#Amazon EC2|Amazon EC2]]<br />
<br />
===Your server===<br />
After importing, your virtual WeBWorK server will be identical to a system created by following the instructions [[Installation Manual for 2.17 on Ubuntu|Installation Manual for 2.17 on Ubuntu]] with Optional Configurations B and C implemented. '''Note that''' Option A (SSL) is not implemented (see [[#Set up WeBWorK to use SSL|Set up WeBWorK to use SSL]] below).<br />
<br />
'''Note''' that on some virtual environments, you may need to take additional actions. See the section [[#Specific Virtual Environments|Specific Virtual Environments]] below.<br />
<br />
You should read through the instructions [[Installation Manual for 2.17 on Ubuntu|Installation Manual for 2.17 on Ubuntu]] in order to understand how your server has been set up. Especially look at<br />
[[Installation Manual for 2.17 on Ubuntu#Notation|Notation in the Installation Manual for 2.17 on Ubuntu]] to understand the notation we use in these instructions.<br />
<br />
==Boot Your Server==<br />
===Log into your server ===<br />
After booting you should see a login prompt (you may have to press <code>&lt;Enter&gt;</code>).<br />
*Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges. We will denote<br />
wwadmin's password by <code><wwadmin password></code>. Initially this is set to <code>wwadmin</code>.<br />
If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.<br />
<br />
===Test your ip address===<br />
Run the command<br />
$ ip address show<br />
and look at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]). If that doesn't help look at [[#Debugging Networking Issues|Debugging Networking Issues]]. '''You have to fix this before you can go on to the next step'''.<br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program. <br />
<br />
You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with <code>copy</code> from the Edit menu or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit menu list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code> or <code>&lt;Shift&gt; &lt;Insert&gt;</code> depending on your application). <br />
<br />
My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. In any event, after testing, read the section [[#Make the WeBWorK Configuration Permanent|Make the WeBWorK Configuration Permanent]] below. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.<br />
<br />
I am assuming your network has been set up automatically.<br />
<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a <br />
terminal emulator running on your host using ssh, or from the terminal on the guest once you login. <br />
<br />
Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will probably see (in the summer)<br />
...<br />
Time zone: Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/New_York". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/New_York<br />
[sudo] password for wwadmin: <wwadmin password><br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
=== Checking for and Installing Hotfixes ===<br />
Follow the instructions at [[Installation_Manual_for_2.17_on_Ubuntu#Checking_for_and_Installing_Hotfixes|Checking for and Installing Hotfixes in the Installation Manual for 2.17 on Ubuntu]].<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the virtual machine image was built. <br />
You should definitely update the webwork2 code.'''<br />
--><br />
<!--<br />
'''Important: The are bug fixes for the pg code that occurred after the virtual machine image was built. You should definitely update the pg code.'''<br />
--><br />
<br />
=== WeBWorK configuration ===<br />
<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
First we have to edit information about the Apache2 server setup. <br />
Search for <code>192.168.138.132</code> and replace that by your the new ip address you found above (<code>192.168.76.128</code> in our example above). <br />
<br />
'''But wait, this can be tricky'''. If you set up port forwarding (as we had to for VirtualBox), then instead use the code<br />
$server_root_url = 'http://localhost';<br />
<br />
The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM)<br />
<br />
$server_root_url = 'http://192.168.76.128';<br />
<br />
where of course your ip address may be different. The "http://" is important. <br />
<br />
'''Remark'''. First of all, let me admit I don't understand the above - it just works. If this is not set correctly (and I don't really understand what "correctly" means), then when you test the Library Browser, e.g. by clicking on <code>Library Browser</code> on the <code>Main Menu</code>, then on <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, you will not be able to select a <code>Chapter</code> and you will see an error message similar to<br />
183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.<br />
If you google this message, you will find a lot of people have seen this error and the most common reason is that <code>$server_root_url</code> has not been set correctly, whatever "correctly" means. A common error is to use forget <code>http://</code> or to use <code>http://</code> when you should use <code>https://</code> (or vice versa) or to just have the wrong domain name or ip address.<br />
<br />
We now continue editing <code>site.conf</code> <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then.<br />
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.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.'''<br />
<br />
Then save the file and Quit.<br />
<br />
==== The defaults.config file ====<br />
<br />
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 <code>defaults.config</code>, you will see the lines<br />
<br />
$mail{allowedRecipients} = [<br />
#'prof1@yourserver.yourdomain.edu',<br />
#'prof2@yourserver.yourdomain.edu',<br />
];<br />
<br />
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.<br />
<br />
==== Edit the localOverrides.conf file ====<br />
Now backup and edit localOverrides.conf 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).<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak1<br />
$ nano localOverrides.conf<br />
<br />
Now add and then edit the lines<br />
<br />
<br />
$mail{allowedRecipients} = [<br />
#'prof1@yourserver.yourdomain.edu',<br />
#'prof2@yourserver.yourdomain.edu',<br />
];<br />
Of course you have to remove the comment character #.<br />
<br />
Then save the file and Quit.<br />
<br />
'''Now restart apache so that our changes to the conf files takes effect.'''<br />
<br />
$ sudo apache2ctl restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
===Set up WeBWorK to use SSL===<br />
This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.<br />
<br />
Follow the instructions at [[Installation_Manual_for_2.17_on_Ubuntu#Implement Option A (SSL)|Implement Option A (SSL) in the Installation Manual for 2.17 on Ubuntu]].<br />
<br />
===Finish up===<br />
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.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://192.168.76.128/webwork2</code> where of course you should use your actual ip address. If you have already set up https and haven't setup the redirect, then you should use <code>https://192.168.76.128/webwork2</code> . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.<br />
<br />
<br />
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 <code>/var/log/apache2/error.log</code>. And you should look at [[Installation_Manual_for_2.17_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.17 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Make the WeBWorK Configuration Permanent==<br />
<br />
Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with <code>ip address show</code>) and used that when editing the <code>site.conf</code> file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.<br />
# The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the <code>site.conf</code> file. <br />
# The other method is to setup networking to use a fixed specific ip address for your server and use that in the <code>site.conf</code> file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the [[#Networking_2|Networking]] section under [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] below for information on editing these files. You can search the web for information on the correct syntax to use.<br />
<br />
Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections [[#Edit the site.conf file|Edit the site.conf file]] and [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]].<br />
<br />
Remember that any time you edit WeBWorK's configuration files, you have the restart Apache2 for the changes to take effect. For networking changes to take effect, you should reboot the server.<br />
<br />
==Passwords==<br />
It is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access.<br />
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.<br />
<br />
====Change the password for wwadmin====<br />
<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$ <br />
'''Do not forget the new <code>&lt;wwadmin password&gt;</code> that you just entered.''' Below when we refer to <wwadmin password>, we mean the '''new''' <wwadmin password>.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = "wwadmin";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. We refer to this password as <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart Apache so the changes take effect.<br />
<br />
$ sudo apache2ctl graceful<br />
[sudo] password for wwadmin: <wwadmin password><br />
$<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,authentication_string,password,plugin,host FROM mysql.user;<br />
<br />
You will see a table with two users (<code>root</code> and <code>webworkWrite</code>). <br />
You should see that both users have a valid password (which will be displayed in encrypted form) and <code>root</code> is authenticated by a socket. <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT Host, User, password FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
Finally a note on the MariaDB root password. In Ubuntu systems running MySQL 5.7 (and later versions), the MariaDBL 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.16_on_Ubuntu#Securing_the_Database]]) we had to set a password for the MariaDB root user and<br />
that password was set to "wwadmin" even though it is not used. If you ever change how the MariaDB root user is authenticated (you shouldn't!!), remember this.<br />
<br />
====Change the password for admin====<br />
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.<br />
<br />
====Change the password for profa====<br />
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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
http://192.168.76.128/webwork2/admin</code> <br />
http://192.168.76.128/webwork2/mytestcourse</code> <br />
where of course you should use your actual ip address.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Apache's configuration according to your server's memory===<br />
Look at [[Installation_Manual_for_2.17_on_Ubuntu#Edit_mpm_prefork.conf|Edit mpm_prefork.conf in the Installation Manual for 2.17 on Ubuntu ]] and adjust "MaxRequestWorkers"<br />
according to the rule of thumb given there.<br />
<br />
===Set up access to Apache's server-info and servo-status===<br />
<br />
This isn't really necessary but you should look at [[Installation_Manual_for_2.17_on_Ubuntu#enabling_info.conf_and_status.conf_in_Ubuntu|the info.conf and status.conf section in Installation Manual for 2.17 on Ubuntu]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in [[#Specific Virtual Environments|Specific Virtual Environments]] below. <br />
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<br />
20 GB to 30GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 19G 11G 7.3G 59% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/sda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 21.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags: <br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 20.0GB 20.0GB ext4<br />
<br />
(parted)<br />
<br />
We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command<br />
(parted) resizepart<br />
Partition number? 2<br />
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [20GB]? 30GB<br />
(parted)<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 31.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags:<br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 30.0GB 30.0GB ext4<br />
<br />
(parted)<br />
Notice we now have a 30 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below<br />
$ sudo resize2fs /dev/sda2<br />
[sudo] password for wwadmin: <wwadmin password><br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/sda2 is mounted on /; on-line resizing required<br />
old_desc_blocks = 2, new_desc_blocks = 3<br />
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 29G 11G 18G 38% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
*'''Option A''' is not implemented. '''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
==Specific Virtual Environments==<br />
Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of<br />
the specific environments we have information on:<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 15 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
<br />
===VMware Workstation 16 Player running on a Windows 11 host===<br />
====Importing the ova File====<br />
For VMware Player select Player, File, Open and then browse to the location of the <code>WW2.17_Ubuntu22.04_Server.ova</code> file and open the file.<br />
Name your machine and select a storage path and then hit Import<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
====Accessing your server from your host====<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the '''WeBWorK''' Welcome page. <br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 6 running on a Windows 11 host===<br />
<br />
====Importing the ova File====<br />
For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the <code>WW2.17_Ubuntu22.04_Server.ova</code> file and open the file. Click Next, and then Import. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Initially networking will be broken. Do the following from your guest WeBWorK system<br />
$ sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
...<br />
logical name: enp0s17<br />
version: 02<br />
serial: 08:00:27:30:28:b6<br />
...<br />
Remember the logical name from your system as we will need it below. We have to backup and then edit one file.<br />
<br />
$ cd /etc/netplan/<br />
$ sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak1<br />
[sudo] password for wwadmin: <wwadmin password> <br />
Now edit the <code> 00-installer-config.yaml</code> file<br />
$ sudo nano 00-installer-config.yaml<br />
It should look like (I had to stretch the window to see the whole file):<br />
# This is the network config written by 'subiquity'<br />
network:<br />
ethernets:<br />
ens33:<br />
dhcp4: true<br />
version: 2<br />
Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.<br />
<br />
<br />
Now reboot your server,e.g.<br />
$ sudo reboot<br />
[sudo] password for wwadmin: <wwadmin password> <br />
login and run the command<br />
$ ip address show<br />
and look at the output, something like<br />
... <br />
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000<br />
link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff<br />
inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17<br />
...<br />
<br />
We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below. <br />
<br />
In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network"<br />
Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:<br />
<br />
{| class="wikitable"<br />
|+Port Forwarding<br />
!Name<br />
!Protocol<br />
!Host IP<br />
!Host Port<br />
!Guest IP<br />
!Guest Port<br />
|-<br />
|ssh<br />
|TCP<br />
|127.0.0.1<br />
|2222<br />
|10.0.2.15<br />
|22<br />
|-<br />
|https<br />
|TCP<br />
|127.0.0.1<br />
|4443<br />
|10.0.2.15<br />
|443<br />
|-<br />
|http<br />
|TCP<br />
|127.0.0.1<br />
|8081<br />
|10.0.2.15<br />
|80<br />
|}<br />
Double check that you have entered everything correctly ('''using''' your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".<br />
<br />
Now boot your server.<br />
<br />
====Accessing your server from your host====<br />
We need to employ the port forwarding rules above.<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up with the port forwarding rules above, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and you should the '''WeBWorK''' Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.<br />
<br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your guest id shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list <br />
(probably "WW2.17_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. <br />
Click “Apply” when you're done.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host===<br />
<br />
====Importing the ova File====<br />
For VMware Player select File, Open a Virtual Machine and then browse to the location of the <code>WW2.17_Ubuntu22.04_Server.ova</code> file and import the file.<br />
<br />
You may get a warning message but on retry it will work (strange since the ova image was created on VMware Player).<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
Accessing your server is exactly the same as in [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]] above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.76.128<br />
where of course you need to use the ip address of your WeBWorK guest server.<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 6 running on a Ubuntu 22.04 Desktop host===<br />
====Importing the ova File====<br />
Importing the ova File is exactly the same as in [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Accessing your server involves the same procedure as in [[#VirtualBox 6 running on a Windows 101 host|VirtualBox 6 running on a Windows 11 host]] above. So you have to<br />
# Find the name and MAC address of the virtual nic (network interface card)<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
# Set up port forwarding<br />
See [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above for details.<br />
<br />
'''Except''' that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh -p 2222 wwadmin@127.0.0.1<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
The procedure is the same as in [[#Expand the disk drive_2|Expand the disk drive]] the Windows 11 case above.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===QEMU/KVM running on a Ubuntu 22.04 Desktop host===<br />
The procedure should be very similar to that documented in<br />
[[Installing_from_WW2.15_Ubuntu20.04_Server_Virtual_Machine_Image#QEMU.2FKVM_running_on_a_Ubuntu_20.04_Desktop_host]]<br />
except that the <code>virt-convert</code> program no longer seems to be contained in the standard Ubuntu 22.04 repositories and you will have to find it or an alternative. We have not tested the ova on KVM.<br />
<br />
===Amazon EC2===<br />
While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the [[WeBWorK_2.17_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image]] is faster and easier anyway.<br />
<br />
==Debugging Networking Issues==<br />
If after reading the information above on networking you are still having problems, maybe the information below will be of help.<br />
<br />
===One method===<br />
There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms:<br />
$ ip address show<br />
does not return an ip address and the WW guest can not access the outside world.<br />
<br />
In VirtualBox I built another guest from the <code>ubuntu-22.04-live-server-amd64.iso</code> using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by<br />
sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files<br />
/etc/netplan/00-installer-config.yaml<br />
and<br />
/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg<br />
BUT in the WW guest the information did not agree. This led to the information given in [[#Networking_2|the Networking section of VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
===Ports on your WeBWorK guest===<br />
Run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you see something like<br />
<br />
systemd-r 697 systemd-resolve 13u IPv4 19596 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
sshd 772 root 3u IPv4 21834 0t0 TCP *:22 (LISTEN)<br />
sshd 772 root 4u IPv6 21845 0t0 TCP *:22 (LISTEN)<br />
lighttpd 810 www-data 4u IPv4 22509 0t0 TCP *:8080 (LISTEN)<br />
mysqld 856 mysql 31u IPv6 23312 0t0 TCP *:33060 (LISTEN)<br />
mysqld 856 mysql 33u IPv4 23654 0t0 TCP 127.0.0.1:3306 (LISTEN)<br />
Rserve 865 rserveuser 3u IPv4 22878 0t0 TCP 127.0.0.1:6311 (LISTEN)<br />
/usr/sbin 946 root 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 956 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 957 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 958 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 959 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 960 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
<br />
===Ports on your Windows 11 Pro host===<br />
Open a Power Shell command window as an administrator and run the command (it can take awhile)<br />
PS C:\> netstat -ab<br />
<br />
Active Connections<br />
<br />
Proto Local Address Foreign Address State<br />
TCP 0.0.0.0:135 desktop:0 LISTENING<br />
RpcSs<br />
[svchost.exe]<br />
TCP 0.0.0.0:443 desktop:0 LISTENING<br />
[vmware-hostd.exe]<br />
TCP 0.0.0.0:445 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:903 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:913 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:2869 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:3306 desktop:0 LISTENING<br />
[mysqld.exe]<br />
...<br />
TCP 0.0.0.0:6000 desktop:0 LISTENING<br />
[XWin_MobaX.exe]<br />
TCP 0.0.0.0:49664 desktop:0 LISTENING<br />
...<br />
TCP 127.0.0.1:2222 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52916 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52917 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:4443 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
...<br />
<br />
===Ports on your Linux host===<br />
<br />
Run the command<br />
<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for ****: <br />
<br />
and you should see something like the following<br />
systemd-r 436 systemd-resolve 13u IPv4 18620 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
vmware-au 1284 root 10u IPv6 33012 0t0 TCP *:902 (LISTEN)<br />
vmware-au 1284 root 11u IPv4 33013 0t0 TCP *:902 (LISTEN)<br />
sshd 8786 root 3u IPv4 114131 0t0 TCP *:22 (LISTEN)<br />
sshd 8786 root 4u IPv6 114133 0t0 TCP *:22 (LISTEN)<br />
cupsd 12124 root 6u IPv6 138503 0t0 TCP [::1]:631 (LISTEN)<br />
cupsd 12124 root 7u IPv4 138504 0t0 TCP 127.0.0.1:631 (LISTEN)<br />
VirtualBo 17065 wwadmin 48u IPv4 185297 0t0 TCP 127.0.0.1:8081 (LISTEN)<br />
VirtualBo 17065 wwadmin 49u IPv4 185298 0t0 TCP 127.0.0.1:4443 (LISTEN)<br />
VirtualBo 17065 wwadmin 50u IPv4 185299 0t0 TCP 127.0.0.1:8080 (LISTEN)<br />
VirtualBo 17065 wwadmin 51u IPv4 185300 0t0 TCP 127.0.0.1:2222 (LISTEN)<br />
<br />
Notice that port forwarding for VirtualBox has been set up correctly.<br />
<br />
<br />
<br />
-- Main.ArnoldPizer - August 2022 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.17_Ubuntu_Server_22.04_LTS_Virtual_Machine_Image&diff=24174WeBWorK 2.17 Ubuntu Server 22.04 LTS Virtual Machine Image2023-09-11T18:02:15Z<p>Apizer: Undo revision 24173 by Apizer (talk)</p>
<hr />
<div><!--<br />
{{UnderConstruction}} <br />
--><br />
<br />
These instructions cover the installation of the Ubuntu Server 22.04 LTS 64 bit operating system and WeBWorK 2.17 using the WeBWorK Virtual Machine Image. <br />
<br />
The WeBWorK Virtual Machine Image is an <code>.ova</code> file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, QEMU/KVM, etc. <br />
<br />
This image file has been tested on <br />
* VMware Workstation 16 Player<br />
* VirtualBox 6<br />
<br />
This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Apache2, MariaDB, R server, log rotation, etc.) installed and configured. <br />
<br />
== Installing from WW2.17 Ubuntu22.04 Server Virtual Machine Image ==<br />
<br />
===Overview===<br />
After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.17, Apache2, MariaDB, R server, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who has sudo privileges), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> who has professor privileges (see below).<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.17 at<br />
[[Installation_Manual_for_2.17_on_Ubuntu|Installation Manual for 2.17 on Ubuntu]].<br />
<br />
===Download the ova image===<br />
<br />
Download the .sha checksum and the .ova files from the WeBWorK Download Site below. <br />
<br />
You want to download the files <code>WW2.17_Ubuntu22.04_Server.ova.sha</code> and <code>WW2.17_Ubuntu22.04_Server.ova</code><br />
The ova is a 6.3 GB file.<br />
<br />
* [http://webwork.maa.org/ww-downloads/wwdownload.html WeBWorK Download Site]<br />
<br />
Verify the SHA1 checksum of your downloaded file <code>WW2.17_Ubuntu22.04_Server.ova</code> agrees with the one in <code>WW2.17_Ubuntu22.04_Server.ova.sha</code>.<br />
<br />
===OVA and OVF files===<br />
The <code>.ova</code> file is simply a tar bundle containing an <code>.ovf</code> file, one or more <code>.vmdk</code> files, a <code>.mf</code> file and possibly other files.<br />
* The <code>.ovf</code> file is an XML file which describes the packaged virtual machine and is human-readable. <br />
* The <code>.vmdk</code> file(s) contain the disk images(s).<br />
* Possibly other files<br />
* The <code>.mf</code> file contains SHA1 checksums for the above files.<br />
<br />
You can import a virtual machine either from an <code>.ova</code> file or from the <code>.ovf</code>, <code>.vmdk</code>, <code>.mf</code> collection. Sometimes importing from the <code>.ova</code> file may fail whereas importing from the <code>.ovf</code> or <code>.vmdk</code> file will succeed.<br />
<br />
You can extract the files in <code>WW2.18_Ubuntu22.04_Server.ova</code> with the command <br />
<br />
$ tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
<br />
You then can look at (and possibly edit) the human readable <code>WW2.18_Ubuntu22.04_Server.ofv</code> file. If you do edit the <code>WW2.18_Ubuntu22.04_Server.ofv</code> file, you will also have to compute the new SHA1 checksum and replace the old one in the <code>WW2.18_Ubuntu22.04_Server.mf</code> file for the files to be usable.<br />
<br />
===Installing the WeBWorK Virtual Machine Image ===<br />
<br />
Import the file <code>WW2.17_Ubuntu22.04_Server.ova</code> into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 16 Player <br />
running on a Windows 11 Pro host. It has been tested on <br />
* VMware Workstation 16 Player running on a Windows 11 host (Home and Pro editions)<br />
* VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host<br />
* VirtualBox 6 running on a Windows 11 host (Home and Pro editions)<br />
* VirtualBox 6 running on a Ubuntu 22.04 Desktop host<br />
'''See [[#Specific Virtual Environments|Specific Virtual Environments]] below for installation information on specific virtual environments.'''<br />
<br />
====Processors, Memory, Hard Disk, Networking====<br />
The WeBWorK Virtual Machine Image was created with the following parameters:<br />
*20 GB dynamically allocated disk drive in VMDK format (single file) of which 11 GB is used<br />
*4 GB memory<br />
*2 cpu<br />
These resources are OK for testing and should suffice for small courses but it is possible to overwhelm the machine.<br />
<br />
Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 16 Player running on a Windows 11 host). You should adjust these resources either when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk is more complicated. See [[#Specific Virtual Environments|Specific Virtual Environments]] below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see [[#Increase Disk Space|Increase Disk Space]] below). <br />
<br />
Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]) and/or look at [[#Debugging Networking Issues|Debugging Networking Issues]].<br />
<br />
===Import the .ova file===<br />
There may be specific information for your situation below. See<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
* [[#Amazon EC2|Amazon EC2]]<br />
<br />
===Your server===<br />
After importing, your virtual WeBWorK server will be identical to a system created by following the instructions [[Installation Manual for 2.17 on Ubuntu|Installation Manual for 2.17 on Ubuntu]] with Optional Configurations B and C implemented. '''Note that''' Option A (SSL) is not implemented (see [[#Set up WeBWorK to use SSL|Set up WeBWorK to use SSL]] below).<br />
<br />
'''Note''' that on some virtual environments, you may need to take additional actions. See the section [[#Specific Virtual Environments|Specific Virtual Environments]] below.<br />
<br />
You should read through the instructions [[Installation Manual for 2.17 on Ubuntu|Installation Manual for 2.17 on Ubuntu]] in order to understand how your server has been set up. Especially look at<br />
[[Installation Manual for 2.17 on Ubuntu#Notation|Notation in the Installation Manual for 2.17 on Ubuntu]] to understand the notation we use in these instructions.<br />
<br />
==Boot Your Server==<br />
===Log into your server ===<br />
After booting you should see a login prompt (you may have to press <code>&lt;Enter&gt;</code>).<br />
*Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges. We will denote<br />
wwadmin's password by <code><wwadmin password></code>. Initially this is set to <code>wwadmin</code>.<br />
If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.<br />
<br />
===Test your ip address===<br />
Run the command<br />
$ ip address show<br />
and look at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]). If that doesn't help look at [[#Debugging Networking Issues|Debugging Networking Issues]]. '''You have to fix this before you can go on to the next step'''.<br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program. <br />
<br />
You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with <code>copy</code> from the Edit menu or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit menu list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code> or <code>&lt;Shift&gt; &lt;Insert&gt;</code> depending on your application). <br />
<br />
My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. In any event, after testing, read the section [[#Make the WeBWorK Configuration Permanent|Make the WeBWorK Configuration Permanent]] below. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.<br />
<br />
I am assuming your network has been set up automatically.<br />
<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a <br />
terminal emulator running on your host using ssh, or from the terminal on the guest once you login. <br />
<br />
Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will probably see (in the summer)<br />
...<br />
Time zone: Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/New_York". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/New_York<br />
[sudo] password for wwadmin: <wwadmin password><br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
=== Checking for and Installing Hotfixes ===<br />
Follow the instructions at [[Installation_Manual_for_2.17_on_Ubuntu#Checking_for_and_Installing_Hotfixes|Checking for and Installing Hotfixes in the Installation Manual for 2.17 on Ubuntu]].<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the virtual machine image was built. <br />
You should definitely update the webwork2 code.'''<br />
--><br />
<!--<br />
'''Important: The are bug fixes for the pg code that occurred after the virtual machine image was built. You should definitely update the pg code.'''<br />
--><br />
<br />
=== WeBWorK configuration ===<br />
<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
First we have to edit information about the Apache2 server setup. <br />
Search for <code>192.168.138.132</code> and replace that by your the new ip address you found above (<code>192.168.76.128</code> in our example above). <br />
<br />
'''But wait, this can be tricky'''. If you set up port forwarding (as we had to for VirtualBox), then instead use the code<br />
$server_root_url = 'http://localhost';<br />
<br />
The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM)<br />
<br />
$server_root_url = 'http://192.168.76.128';<br />
<br />
where of course your ip address may be different. The "http://" is important. <br />
<br />
'''Remark'''. First of all, let me admit I don't understand the above - it just works. If this is not set correctly (and I don't really understand what "correctly" means), then when you test the Library Browser, e.g. by clicking on <code>Library Browser</code> on the <code>Main Menu</code>, then on <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, you will not be able to select a <code>Chapter</code> and you will see an error message similar to<br />
183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.<br />
If you google this message, you will find a lot of people have seen this error and the most common reason is that <code>$server_root_url</code> has not been set correctly, whatever "correctly" means. A common error is to use forget <code>http://</code> or to use <code>http://</code> when you should use <code>https://</code> (or vice versa) or to just have the wrong domain name or ip address.<br />
<br />
We now continue editing <code>site.conf</code> <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then.<br />
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.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.'''<br />
<br />
Then save the file and Quit.<br />
<br />
==== The defaults.config file ====<br />
<br />
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 <code>defaults.config</code>, you will see the lines<br />
<br />
$mail{allowedRecipients} = [<br />
#'prof1@yourserver.yourdomain.edu',<br />
#'prof2@yourserver.yourdomain.edu',<br />
];<br />
<br />
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.<br />
<br />
==== Edit the localOverrides.conf file ====<br />
Now backup and edit localOverrides.conf 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).<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak1<br />
$ nano localOverrides.conf<br />
<br />
Now add and then edit the lines<br />
<br />
<br />
$mail{allowedRecipients} = [<br />
#'prof1@yourserver.yourdomain.edu',<br />
#'prof2@yourserver.yourdomain.edu',<br />
];<br />
Of course you have to remove the comment character #.<br />
<br />
Then save the file and Quit.<br />
<br />
'''Now restart apache so that our changes to the conf files takes effect.'''<br />
<br />
$ sudo apache2ctl restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
===Set up WeBWorK to use SSL===<br />
This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.<br />
<br />
Follow the instructions at [[Installation_Manual_for_2.17_on_Ubuntu#Implement Option A (SSL)|Implement Option A (SSL) in the Installation Manual for 2.17 on Ubuntu]].<br />
<br />
===Finish up===<br />
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.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://192.168.76.128/webwork2</code> where of course you should use your actual ip address. If you have already set up https and haven't setup the redirect, then you should use <code>https://192.168.76.128/webwork2</code> . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.<br />
<br />
<br />
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 <code>/var/log/apache2/error.log</code>. And you should look at [[Installation_Manual_for_2.17_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.17 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Make the WeBWorK Configuration Permanent==<br />
<br />
Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with <code>ip address show</code>) and used that when editing the <code>site.conf</code> file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.<br />
# The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the <code>site.conf</code> file. <br />
# The other method is to setup networking to use a fixed specific ip address for your server and use that in the <code>site.conf</code> file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the [[#Networking_2|Networking]] section under [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] below for information on editing these files. You can search the web for information on the correct syntax to use.<br />
<br />
Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections [[#Edit the site.conf file|Edit the site.conf file]] and [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]].<br />
<br />
Remember that any time you edit WeBWorK's configuration files, you have the restart Apache2 for the changes to take effect. For networking changes to take effect, you should reboot the server.<br />
<br />
==Passwords==<br />
It is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access.<br />
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.<br />
<br />
====Change the password for wwadmin====<br />
<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$ <br />
'''Do not forget the new <code>&lt;wwadmin password&gt;</code> that you just entered.''' Below when we refer to <wwadmin password>, we mean the '''new''' <wwadmin password>.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = "wwadmin";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. We refer to this password as <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart Apache so the changes take effect.<br />
<br />
$ sudo apache2ctl graceful<br />
[sudo] password for wwadmin: <wwadmin password><br />
$<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,authentication_string,password,plugin,host FROM mysql.user;<br />
<br />
You will see a table with two users (<code>root</code> and <code>webworkWrite</code>). <br />
You should see that both users have a valid password (which will be displayed in encrypted form) and <code>root</code> is authenticated by a socket. <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT Host, User, password FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
Finally a note on the MariaDB root password. In Ubuntu systems running MySQL 5.7 (and later versions), the MariaDBL 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.16_on_Ubuntu#Securing_the_Database]]) we had to set a password for the MariaDB root user and<br />
that password was set to "wwadmin" even though it is not used. If you ever change how the MariaDB root user is authenticated (you shouldn't!!), remember this.<br />
<br />
====Change the password for admin====<br />
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.<br />
<br />
====Change the password for profa====<br />
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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
http://192.168.76.128/webwork2/admin</code> <br />
http://192.168.76.128/webwork2/mytestcourse</code> <br />
where of course you should use your actual ip address.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Apache's configuration according to your server's memory===<br />
Look at [[Installation_Manual_for_2.17_on_Ubuntu#Edit_mpm_prefork.conf|Edit mpm_prefork.conf in the Installation Manual for 2.17 on Ubuntu ]] and adjust "MaxRequestWorkers"<br />
according to the rule of thumb given there.<br />
<br />
===Set up access to Apache's server-info and servo-status===<br />
<br />
This isn't really necessary but you should look at [[Installation_Manual_for_2.17_on_Ubuntu#enabling_info.conf_and_status.conf_in_Ubuntu|the info.conf and status.conf section in Installation Manual for 2.17 on Ubuntu]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in [[#Specific Virtual Environments|Specific Virtual Environments]] below. <br />
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<br />
20 GB to 30GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 19G 11G 7.3G 59% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/sda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 21.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags: <br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 20.0GB 20.0GB ext4<br />
<br />
(parted)<br />
<br />
We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command<br />
(parted) resizepart<br />
Partition number? 2<br />
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [20GB]? 30GB<br />
(parted)<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 31.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags:<br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 30.0GB 30.0GB ext4<br />
<br />
(parted)<br />
Notice we now have a 30 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below<br />
$ sudo resize2fs /dev/sda2<br />
[sudo] password for wwadmin: <wwadmin password><br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/sda2 is mounted on /; on-line resizing required<br />
old_desc_blocks = 2, new_desc_blocks = 3<br />
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 29G 11G 18G 38% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
*'''Option A''' is not implemented. '''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
==Specific Virtual Environments==<br />
Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of<br />
the specific environments we have information on:<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 15 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
<br />
===VMware Workstation 16 Player running on a Windows 11 host===<br />
====Importing the ova File====<br />
For VMware Player select Player, File, Open and then browse to the location of the <code>WW2.17_Ubuntu22.04_Server.ova</code> file and open the file.<br />
Name your machine and select a storage path and then hit Import<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
====Accessing your server from your host====<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the '''WeBWorK''' Welcome page. <br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 6 running on a Windows 11 host===<br />
<br />
====Importing the ova File====<br />
For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the <code>WW2.17_Ubuntu22.04_Server.ova</code> file and open the file. Click Next, and then Import. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Initially networking will be broken. Do the following from your guest WeBWorK system<br />
$ sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
...<br />
logical name: enp0s17<br />
version: 02<br />
serial: 08:00:27:30:28:b6<br />
...<br />
Remember the logical name from your system as we will need it below. We have to backup and then edit one file.<br />
<br />
$ cd /etc/netplan/<br />
$ sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak1<br />
[sudo] password for wwadmin: <wwadmin password> <br />
Now edit the <code> 00-installer-config.yaml</code> file<br />
$ sudo nano 00-installer-config.yaml<br />
It should look like (I had to stretch the window to see the whole file):<br />
# This is the network config written by 'subiquity'<br />
network:<br />
ethernets:<br />
ens33:<br />
dhcp4: true<br />
version: 2<br />
Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.<br />
<br />
<br />
Now reboot your server,e.g.<br />
$ sudo reboot<br />
[sudo] password for wwadmin: <wwadmin password> <br />
login and run the command<br />
$ ip address show<br />
and look at the output, something like<br />
... <br />
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000<br />
link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff<br />
inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17<br />
...<br />
<br />
We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below. <br />
<br />
In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network"<br />
Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:<br />
<br />
{| class="wikitable"<br />
|+Port Forwarding<br />
!Name<br />
!Protocol<br />
!Host IP<br />
!Host Port<br />
!Guest IP<br />
!Guest Port<br />
|-<br />
|ssh<br />
|TCP<br />
|127.0.0.1<br />
|2222<br />
|10.0.2.15<br />
|22<br />
|-<br />
|https<br />
|TCP<br />
|127.0.0.1<br />
|4443<br />
|10.0.2.15<br />
|443<br />
|-<br />
|http<br />
|TCP<br />
|127.0.0.1<br />
|8081<br />
|10.0.2.15<br />
|80<br />
|}<br />
Double check that you have entered everything correctly ('''using''' your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".<br />
<br />
Now boot your server.<br />
<br />
====Accessing your server from your host====<br />
We need to employ the port forwarding rules above.<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up with the port forwarding rules above, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and you should the '''WeBWorK''' Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.<br />
<br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your guest id shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list <br />
(probably "WW2.17_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. <br />
Click “Apply” when you're done.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host===<br />
<br />
====Importing the ova File====<br />
For VMware Player select File, Open a Virtual Machine and then browse to the location of the <code>WW2.17_Ubuntu22.04_Server.ova</code> file and import the file.<br />
<br />
You may get a warning message but on retry it will work (strange since the ova image was created on VMware Player).<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
Accessing your server is exactly the same as in [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]] above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.76.128<br />
where of course you need to use the ip address of your WeBWorK guest server.<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 6 running on a Ubuntu 22.04 Desktop host===<br />
====Importing the ova File====<br />
Importing the ova File is exactly the same as in [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Accessing your server involves the same procedure as in [[#VirtualBox 6 running on a Windows 101 host|VirtualBox 6 running on a Windows 11 host]] above. So you have to<br />
# Find the name and MAC address of the virtual nic (network interface card)<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
# Set up port forwarding<br />
See [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above for details.<br />
<br />
'''Except''' that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh -p 2222 wwadmin@127.0.0.1<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
The procedure is the same as in [[#Expand the disk drive_2|Expand the disk drive]] the Windows 11 case above.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===QEMU/KVM running on a Ubuntu 22.04 Desktop host===<br />
The procedure should be very similar to that documented in<br />
[[Installing_from_WW2.15_Ubuntu20.04_Server_Virtual_Machine_Image#QEMU.2FKVM_running_on_a_Ubuntu_20.04_Desktop_host]]<br />
except that the <code>virt-convert</code> program no longer seems to be contained in the standard Ubuntu 22.04 repositories and you will have to find it or an alternative. We have not tested the ova on KVM.<br />
<br />
===Amazon EC2===<br />
While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the [[WeBWorK_2.17_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image]] is faster and easier anyway.<br />
<br />
==Debugging Networking Issues==<br />
If after reading the information above on networking you are still having problems, maybe the information below will be of help.<br />
<br />
===One method===<br />
There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms:<br />
$ ip address show<br />
does not return an ip address and the WW guest can not access the outside world.<br />
<br />
In VirtualBox I built another guest from the <code>ubuntu-22.04-live-server-amd64.iso</code> using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by<br />
sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files<br />
/etc/netplan/00-installer-config.yaml<br />
and<br />
/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg<br />
BUT in the WW guest the information did not agree. This led to the information given in [[#Networking_2|the Networking section of VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
===Ports on your WeBWorK guest===<br />
Run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you see something like<br />
<br />
systemd-r 697 systemd-resolve 13u IPv4 19596 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
sshd 772 root 3u IPv4 21834 0t0 TCP *:22 (LISTEN)<br />
sshd 772 root 4u IPv6 21845 0t0 TCP *:22 (LISTEN)<br />
lighttpd 810 www-data 4u IPv4 22509 0t0 TCP *:8080 (LISTEN)<br />
mysqld 856 mysql 31u IPv6 23312 0t0 TCP *:33060 (LISTEN)<br />
mysqld 856 mysql 33u IPv4 23654 0t0 TCP 127.0.0.1:3306 (LISTEN)<br />
Rserve 865 rserveuser 3u IPv4 22878 0t0 TCP 127.0.0.1:6311 (LISTEN)<br />
/usr/sbin 946 root 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 956 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 957 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 958 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 959 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 960 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
<br />
===Ports on your Windows 11 Pro host===<br />
Open a Power Shell command window as an administrator and run the command (it can take awhile)<br />
PS C:\> netstat -ab<br />
<br />
Active Connections<br />
<br />
Proto Local Address Foreign Address State<br />
TCP 0.0.0.0:135 desktop:0 LISTENING<br />
RpcSs<br />
[svchost.exe]<br />
TCP 0.0.0.0:443 desktop:0 LISTENING<br />
[vmware-hostd.exe]<br />
TCP 0.0.0.0:445 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:903 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:913 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:2869 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:3306 desktop:0 LISTENING<br />
[mysqld.exe]<br />
...<br />
TCP 0.0.0.0:6000 desktop:0 LISTENING<br />
[XWin_MobaX.exe]<br />
TCP 0.0.0.0:49664 desktop:0 LISTENING<br />
...<br />
TCP 127.0.0.1:2222 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52916 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52917 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:4443 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
...<br />
<br />
===Ports on your Linux host===<br />
<br />
Run the command<br />
<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for ****: <br />
<br />
and you should see something like the following<br />
systemd-r 436 systemd-resolve 13u IPv4 18620 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
vmware-au 1284 root 10u IPv6 33012 0t0 TCP *:902 (LISTEN)<br />
vmware-au 1284 root 11u IPv4 33013 0t0 TCP *:902 (LISTEN)<br />
sshd 8786 root 3u IPv4 114131 0t0 TCP *:22 (LISTEN)<br />
sshd 8786 root 4u IPv6 114133 0t0 TCP *:22 (LISTEN)<br />
cupsd 12124 root 6u IPv6 138503 0t0 TCP [::1]:631 (LISTEN)<br />
cupsd 12124 root 7u IPv4 138504 0t0 TCP 127.0.0.1:631 (LISTEN)<br />
VirtualBo 17065 wwadmin 48u IPv4 185297 0t0 TCP 127.0.0.1:8081 (LISTEN)<br />
VirtualBo 17065 wwadmin 49u IPv4 185298 0t0 TCP 127.0.0.1:4443 (LISTEN)<br />
VirtualBo 17065 wwadmin 50u IPv4 185299 0t0 TCP 127.0.0.1:8080 (LISTEN)<br />
VirtualBo 17065 wwadmin 51u IPv4 185300 0t0 TCP 127.0.0.1:2222 (LISTEN)<br />
<br />
Notice that port forwarding for VirtualBox has been set up correctly.<br />
<br />
<br />
<br />
-- Main.ArnoldPizer - August 2022 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.17_Ubuntu_Server_22.04_LTS_Virtual_Machine_Image&diff=24173WeBWorK 2.17 Ubuntu Server 22.04 LTS Virtual Machine Image2023-09-11T18:00:15Z<p>Apizer: /* Installing the WeBWorK Virtual Machine Image */</p>
<hr />
<div><!--<br />
{{UnderConstruction}} <br />
--><br />
<br />
These instructions cover the installation of the Ubuntu Server 22.04 LTS 64 bit operating system and WeBWorK 2.17 using the WeBWorK Virtual Machine Image. <br />
<br />
The WeBWorK Virtual Machine Image is an <code>.ova</code> file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, QEMU/KVM, etc. <br />
<br />
This image file has been tested on <br />
* VMware Workstation 16 Player<br />
* VirtualBox 6<br />
<br />
This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Apache2, MariaDB, R server, log rotation, etc.) installed and configured. <br />
<br />
== Installing from WW2.17 Ubuntu22.04 Server Virtual Machine Image ==<br />
<br />
===Overview===<br />
After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.17, Apache2, MariaDB, R server, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who has sudo privileges), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> who has professor privileges (see below).<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.17 at<br />
[[Installation_Manual_for_2.17_on_Ubuntu|Installation Manual for 2.17 on Ubuntu]].<br />
<br />
===Download the ova image===<br />
<br />
Download the .sha checksum and the .ova files from the WeBWorK Download Site below. <br />
<br />
You want to download the files <code>WW2.17_Ubuntu22.04_Server.ova.sha</code> and <code>WW2.17_Ubuntu22.04_Server.ova</code><br />
The ova is a 6.3 GB file.<br />
<br />
* [http://webwork.maa.org/ww-downloads/wwdownload.html WeBWorK Download Site]<br />
<br />
Verify the SHA1 checksum of your downloaded file <code>WW2.17_Ubuntu22.04_Server.ova</code> agrees with the one in <code>WW2.17_Ubuntu22.04_Server.ova.sha</code>.<br />
<br />
===OVA and OVF files===<br />
The <code>.ova</code> file is simply a tar bundle containing an <code>.ovf</code> file, one or more <code>.vmdk</code> files, a <code>.mf</code> file and possibly other files.<br />
* The <code>.ovf</code> file is an XML file which describes the packaged virtual machine and is human-readable. <br />
* The <code>.vmdk</code> file(s) contain the disk images(s).<br />
* Possibly other files<br />
* The <code>.mf</code> file contains SHA1 checksums for the above files.<br />
<br />
You can import a virtual machine either from an <code>.ova</code> file or from the <code>.ovf</code>, <code>.vmdk</code>, <code>.mf</code> collection. Sometimes importing from the <code>.ova</code> file may fail whereas importing from the <code>.ovf</code> or <code>.vmdk</code> file will succeed.<br />
<br />
You can extract the files in <code>WW2.18_Ubuntu22.04_Server.ova</code> with the command <br />
<br />
$ tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
<br />
You then can look at (and possibly edit) the human readable <code>WW2.18_Ubuntu22.04_Server.ofv</code> file. If you do edit the <code>WW2.18_Ubuntu22.04_Server.ofv</code> file, you will also have to compute the new SHA1 checksum and replace the old one in the <code>WW2.18_Ubuntu22.04_Server.mf</code> file for the files to be usable.<br />
<br />
===Installing the WeBWorK Virtual Machine Image ===<br />
<br />
Import the file <code>WW2.18_Ubuntu22.04_Server.ova</code> into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 17 Player <br />
running on a Windows 11 Pro host. It has been tested on <br />
* VMware Workstation 17 Player running on a Windows 11 host<br />
* VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host<br />
* VirtualBox 7 running on a Windows 11 host<br />
* VirtualBox 7 running on a Ubuntu 22.04 Desktop host<br />
'''See [[#Specific Virtual Environments|Specific Virtual Environments]] below for installation information on specific virtual environments.'''<br />
<br />
====Processors, Memory, Hard Disk, Networking====<br />
The WeBWorK Virtual Machine Image was created with the following parameters:<br />
*20 GB dynamically allocated disk drive in VMDK format (single file) of which 11 GB is used<br />
*4 GB memory<br />
*2 cpu<br />
These resources are OK for testing and should suffice for small courses but it is possible to overwhelm the machine.<br />
<br />
Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 16 Player running on a Windows 11 host). You should adjust these resources either when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk is more complicated. See [[#Specific Virtual Environments|Specific Virtual Environments]] below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see [[#Increase Disk Space|Increase Disk Space]] below). <br />
<br />
Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]) and/or look at [[#Debugging Networking Issues|Debugging Networking Issues]].<br />
<br />
===Import the .ova file===<br />
There may be specific information for your situation below. See<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
* [[#Amazon EC2|Amazon EC2]]<br />
<br />
===Your server===<br />
After importing, your virtual WeBWorK server will be identical to a system created by following the instructions [[Installation Manual for 2.17 on Ubuntu|Installation Manual for 2.17 on Ubuntu]] with Optional Configurations B and C implemented. '''Note that''' Option A (SSL) is not implemented (see [[#Set up WeBWorK to use SSL|Set up WeBWorK to use SSL]] below).<br />
<br />
'''Note''' that on some virtual environments, you may need to take additional actions. See the section [[#Specific Virtual Environments|Specific Virtual Environments]] below.<br />
<br />
You should read through the instructions [[Installation Manual for 2.17 on Ubuntu|Installation Manual for 2.17 on Ubuntu]] in order to understand how your server has been set up. Especially look at<br />
[[Installation Manual for 2.17 on Ubuntu#Notation|Notation in the Installation Manual for 2.17 on Ubuntu]] to understand the notation we use in these instructions.<br />
<br />
==Boot Your Server==<br />
===Log into your server ===<br />
After booting you should see a login prompt (you may have to press <code>&lt;Enter&gt;</code>).<br />
*Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges. We will denote<br />
wwadmin's password by <code><wwadmin password></code>. Initially this is set to <code>wwadmin</code>.<br />
If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.<br />
<br />
===Test your ip address===<br />
Run the command<br />
$ ip address show<br />
and look at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]). If that doesn't help look at [[#Debugging Networking Issues|Debugging Networking Issues]]. '''You have to fix this before you can go on to the next step'''.<br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program. <br />
<br />
You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with <code>copy</code> from the Edit menu or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit menu list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code> or <code>&lt;Shift&gt; &lt;Insert&gt;</code> depending on your application). <br />
<br />
My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. In any event, after testing, read the section [[#Make the WeBWorK Configuration Permanent|Make the WeBWorK Configuration Permanent]] below. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.<br />
<br />
I am assuming your network has been set up automatically.<br />
<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a <br />
terminal emulator running on your host using ssh, or from the terminal on the guest once you login. <br />
<br />
Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will probably see (in the summer)<br />
...<br />
Time zone: Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/New_York". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/New_York<br />
[sudo] password for wwadmin: <wwadmin password><br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
=== Checking for and Installing Hotfixes ===<br />
Follow the instructions at [[Installation_Manual_for_2.17_on_Ubuntu#Checking_for_and_Installing_Hotfixes|Checking for and Installing Hotfixes in the Installation Manual for 2.17 on Ubuntu]].<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the virtual machine image was built. <br />
You should definitely update the webwork2 code.'''<br />
--><br />
<!--<br />
'''Important: The are bug fixes for the pg code that occurred after the virtual machine image was built. You should definitely update the pg code.'''<br />
--><br />
<br />
=== WeBWorK configuration ===<br />
<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
First we have to edit information about the Apache2 server setup. <br />
Search for <code>192.168.138.132</code> and replace that by your the new ip address you found above (<code>192.168.76.128</code> in our example above). <br />
<br />
'''But wait, this can be tricky'''. If you set up port forwarding (as we had to for VirtualBox), then instead use the code<br />
$server_root_url = 'http://localhost';<br />
<br />
The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM)<br />
<br />
$server_root_url = 'http://192.168.76.128';<br />
<br />
where of course your ip address may be different. The "http://" is important. <br />
<br />
'''Remark'''. First of all, let me admit I don't understand the above - it just works. If this is not set correctly (and I don't really understand what "correctly" means), then when you test the Library Browser, e.g. by clicking on <code>Library Browser</code> on the <code>Main Menu</code>, then on <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, you will not be able to select a <code>Chapter</code> and you will see an error message similar to<br />
183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.<br />
If you google this message, you will find a lot of people have seen this error and the most common reason is that <code>$server_root_url</code> has not been set correctly, whatever "correctly" means. A common error is to use forget <code>http://</code> or to use <code>http://</code> when you should use <code>https://</code> (or vice versa) or to just have the wrong domain name or ip address.<br />
<br />
We now continue editing <code>site.conf</code> <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then.<br />
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.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.'''<br />
<br />
Then save the file and Quit.<br />
<br />
==== The defaults.config file ====<br />
<br />
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 <code>defaults.config</code>, you will see the lines<br />
<br />
$mail{allowedRecipients} = [<br />
#'prof1@yourserver.yourdomain.edu',<br />
#'prof2@yourserver.yourdomain.edu',<br />
];<br />
<br />
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.<br />
<br />
==== Edit the localOverrides.conf file ====<br />
Now backup and edit localOverrides.conf 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).<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak1<br />
$ nano localOverrides.conf<br />
<br />
Now add and then edit the lines<br />
<br />
<br />
$mail{allowedRecipients} = [<br />
#'prof1@yourserver.yourdomain.edu',<br />
#'prof2@yourserver.yourdomain.edu',<br />
];<br />
Of course you have to remove the comment character #.<br />
<br />
Then save the file and Quit.<br />
<br />
'''Now restart apache so that our changes to the conf files takes effect.'''<br />
<br />
$ sudo apache2ctl restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
===Set up WeBWorK to use SSL===<br />
This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.<br />
<br />
Follow the instructions at [[Installation_Manual_for_2.17_on_Ubuntu#Implement Option A (SSL)|Implement Option A (SSL) in the Installation Manual for 2.17 on Ubuntu]].<br />
<br />
===Finish up===<br />
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.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://192.168.76.128/webwork2</code> where of course you should use your actual ip address. If you have already set up https and haven't setup the redirect, then you should use <code>https://192.168.76.128/webwork2</code> . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.<br />
<br />
<br />
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 <code>/var/log/apache2/error.log</code>. And you should look at [[Installation_Manual_for_2.17_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.17 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Make the WeBWorK Configuration Permanent==<br />
<br />
Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with <code>ip address show</code>) and used that when editing the <code>site.conf</code> file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.<br />
# The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the <code>site.conf</code> file. <br />
# The other method is to setup networking to use a fixed specific ip address for your server and use that in the <code>site.conf</code> file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the [[#Networking_2|Networking]] section under [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] below for information on editing these files. You can search the web for information on the correct syntax to use.<br />
<br />
Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections [[#Edit the site.conf file|Edit the site.conf file]] and [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]].<br />
<br />
Remember that any time you edit WeBWorK's configuration files, you have the restart Apache2 for the changes to take effect. For networking changes to take effect, you should reboot the server.<br />
<br />
==Passwords==<br />
It is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access.<br />
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.<br />
<br />
====Change the password for wwadmin====<br />
<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$ <br />
'''Do not forget the new <code>&lt;wwadmin password&gt;</code> that you just entered.''' Below when we refer to <wwadmin password>, we mean the '''new''' <wwadmin password>.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = "wwadmin";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. We refer to this password as <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart Apache so the changes take effect.<br />
<br />
$ sudo apache2ctl graceful<br />
[sudo] password for wwadmin: <wwadmin password><br />
$<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,authentication_string,password,plugin,host FROM mysql.user;<br />
<br />
You will see a table with two users (<code>root</code> and <code>webworkWrite</code>). <br />
You should see that both users have a valid password (which will be displayed in encrypted form) and <code>root</code> is authenticated by a socket. <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT Host, User, password FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
Finally a note on the MariaDB root password. In Ubuntu systems running MySQL 5.7 (and later versions), the MariaDBL 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.16_on_Ubuntu#Securing_the_Database]]) we had to set a password for the MariaDB root user and<br />
that password was set to "wwadmin" even though it is not used. If you ever change how the MariaDB root user is authenticated (you shouldn't!!), remember this.<br />
<br />
====Change the password for admin====<br />
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.<br />
<br />
====Change the password for profa====<br />
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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
http://192.168.76.128/webwork2/admin</code> <br />
http://192.168.76.128/webwork2/mytestcourse</code> <br />
where of course you should use your actual ip address.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Apache's configuration according to your server's memory===<br />
Look at [[Installation_Manual_for_2.17_on_Ubuntu#Edit_mpm_prefork.conf|Edit mpm_prefork.conf in the Installation Manual for 2.17 on Ubuntu ]] and adjust "MaxRequestWorkers"<br />
according to the rule of thumb given there.<br />
<br />
===Set up access to Apache's server-info and servo-status===<br />
<br />
This isn't really necessary but you should look at [[Installation_Manual_for_2.17_on_Ubuntu#enabling_info.conf_and_status.conf_in_Ubuntu|the info.conf and status.conf section in Installation Manual for 2.17 on Ubuntu]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in [[#Specific Virtual Environments|Specific Virtual Environments]] below. <br />
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<br />
20 GB to 30GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 19G 11G 7.3G 59% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/sda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 21.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags: <br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 20.0GB 20.0GB ext4<br />
<br />
(parted)<br />
<br />
We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command<br />
(parted) resizepart<br />
Partition number? 2<br />
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [20GB]? 30GB<br />
(parted)<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 31.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags:<br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 30.0GB 30.0GB ext4<br />
<br />
(parted)<br />
Notice we now have a 30 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below<br />
$ sudo resize2fs /dev/sda2<br />
[sudo] password for wwadmin: <wwadmin password><br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/sda2 is mounted on /; on-line resizing required<br />
old_desc_blocks = 2, new_desc_blocks = 3<br />
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 29G 11G 18G 38% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
*'''Option A''' is not implemented. '''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
==Specific Virtual Environments==<br />
Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of<br />
the specific environments we have information on:<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 15 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
<br />
===VMware Workstation 16 Player running on a Windows 11 host===<br />
====Importing the ova File====<br />
For VMware Player select Player, File, Open and then browse to the location of the <code>WW2.17_Ubuntu22.04_Server.ova</code> file and open the file.<br />
Name your machine and select a storage path and then hit Import<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
====Accessing your server from your host====<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the '''WeBWorK''' Welcome page. <br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 6 running on a Windows 11 host===<br />
<br />
====Importing the ova File====<br />
For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the <code>WW2.17_Ubuntu22.04_Server.ova</code> file and open the file. Click Next, and then Import. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Initially networking will be broken. Do the following from your guest WeBWorK system<br />
$ sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
...<br />
logical name: enp0s17<br />
version: 02<br />
serial: 08:00:27:30:28:b6<br />
...<br />
Remember the logical name from your system as we will need it below. We have to backup and then edit one file.<br />
<br />
$ cd /etc/netplan/<br />
$ sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak1<br />
[sudo] password for wwadmin: <wwadmin password> <br />
Now edit the <code> 00-installer-config.yaml</code> file<br />
$ sudo nano 00-installer-config.yaml<br />
It should look like (I had to stretch the window to see the whole file):<br />
# This is the network config written by 'subiquity'<br />
network:<br />
ethernets:<br />
ens33:<br />
dhcp4: true<br />
version: 2<br />
Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.<br />
<br />
<br />
Now reboot your server,e.g.<br />
$ sudo reboot<br />
[sudo] password for wwadmin: <wwadmin password> <br />
login and run the command<br />
$ ip address show<br />
and look at the output, something like<br />
... <br />
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000<br />
link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff<br />
inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17<br />
...<br />
<br />
We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below. <br />
<br />
In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network"<br />
Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:<br />
<br />
{| class="wikitable"<br />
|+Port Forwarding<br />
!Name<br />
!Protocol<br />
!Host IP<br />
!Host Port<br />
!Guest IP<br />
!Guest Port<br />
|-<br />
|ssh<br />
|TCP<br />
|127.0.0.1<br />
|2222<br />
|10.0.2.15<br />
|22<br />
|-<br />
|https<br />
|TCP<br />
|127.0.0.1<br />
|4443<br />
|10.0.2.15<br />
|443<br />
|-<br />
|http<br />
|TCP<br />
|127.0.0.1<br />
|8081<br />
|10.0.2.15<br />
|80<br />
|}<br />
Double check that you have entered everything correctly ('''using''' your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".<br />
<br />
Now boot your server.<br />
<br />
====Accessing your server from your host====<br />
We need to employ the port forwarding rules above.<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up with the port forwarding rules above, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and you should the '''WeBWorK''' Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.<br />
<br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your guest id shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list <br />
(probably "WW2.17_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. <br />
Click “Apply” when you're done.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host===<br />
<br />
====Importing the ova File====<br />
For VMware Player select File, Open a Virtual Machine and then browse to the location of the <code>WW2.17_Ubuntu22.04_Server.ova</code> file and import the file.<br />
<br />
You may get a warning message but on retry it will work (strange since the ova image was created on VMware Player).<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
Accessing your server is exactly the same as in [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]] above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.76.128<br />
where of course you need to use the ip address of your WeBWorK guest server.<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 6 running on a Ubuntu 22.04 Desktop host===<br />
====Importing the ova File====<br />
Importing the ova File is exactly the same as in [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Accessing your server involves the same procedure as in [[#VirtualBox 6 running on a Windows 101 host|VirtualBox 6 running on a Windows 11 host]] above. So you have to<br />
# Find the name and MAC address of the virtual nic (network interface card)<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
# Set up port forwarding<br />
See [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above for details.<br />
<br />
'''Except''' that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh -p 2222 wwadmin@127.0.0.1<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
The procedure is the same as in [[#Expand the disk drive_2|Expand the disk drive]] the Windows 11 case above.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===QEMU/KVM running on a Ubuntu 22.04 Desktop host===<br />
The procedure should be very similar to that documented in<br />
[[Installing_from_WW2.15_Ubuntu20.04_Server_Virtual_Machine_Image#QEMU.2FKVM_running_on_a_Ubuntu_20.04_Desktop_host]]<br />
except that the <code>virt-convert</code> program no longer seems to be contained in the standard Ubuntu 22.04 repositories and you will have to find it or an alternative. We have not tested the ova on KVM.<br />
<br />
===Amazon EC2===<br />
While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the [[WeBWorK_2.17_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image]] is faster and easier anyway.<br />
<br />
==Debugging Networking Issues==<br />
If after reading the information above on networking you are still having problems, maybe the information below will be of help.<br />
<br />
===One method===<br />
There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms:<br />
$ ip address show<br />
does not return an ip address and the WW guest can not access the outside world.<br />
<br />
In VirtualBox I built another guest from the <code>ubuntu-22.04-live-server-amd64.iso</code> using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by<br />
sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files<br />
/etc/netplan/00-installer-config.yaml<br />
and<br />
/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg<br />
BUT in the WW guest the information did not agree. This led to the information given in [[#Networking_2|the Networking section of VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
===Ports on your WeBWorK guest===<br />
Run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you see something like<br />
<br />
systemd-r 697 systemd-resolve 13u IPv4 19596 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
sshd 772 root 3u IPv4 21834 0t0 TCP *:22 (LISTEN)<br />
sshd 772 root 4u IPv6 21845 0t0 TCP *:22 (LISTEN)<br />
lighttpd 810 www-data 4u IPv4 22509 0t0 TCP *:8080 (LISTEN)<br />
mysqld 856 mysql 31u IPv6 23312 0t0 TCP *:33060 (LISTEN)<br />
mysqld 856 mysql 33u IPv4 23654 0t0 TCP 127.0.0.1:3306 (LISTEN)<br />
Rserve 865 rserveuser 3u IPv4 22878 0t0 TCP 127.0.0.1:6311 (LISTEN)<br />
/usr/sbin 946 root 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 956 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 957 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 958 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 959 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 960 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
<br />
===Ports on your Windows 11 Pro host===<br />
Open a Power Shell command window as an administrator and run the command (it can take awhile)<br />
PS C:\> netstat -ab<br />
<br />
Active Connections<br />
<br />
Proto Local Address Foreign Address State<br />
TCP 0.0.0.0:135 desktop:0 LISTENING<br />
RpcSs<br />
[svchost.exe]<br />
TCP 0.0.0.0:443 desktop:0 LISTENING<br />
[vmware-hostd.exe]<br />
TCP 0.0.0.0:445 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:903 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:913 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:2869 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:3306 desktop:0 LISTENING<br />
[mysqld.exe]<br />
...<br />
TCP 0.0.0.0:6000 desktop:0 LISTENING<br />
[XWin_MobaX.exe]<br />
TCP 0.0.0.0:49664 desktop:0 LISTENING<br />
...<br />
TCP 127.0.0.1:2222 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52916 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52917 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:4443 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
...<br />
<br />
===Ports on your Linux host===<br />
<br />
Run the command<br />
<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for ****: <br />
<br />
and you should see something like the following<br />
systemd-r 436 systemd-resolve 13u IPv4 18620 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
vmware-au 1284 root 10u IPv6 33012 0t0 TCP *:902 (LISTEN)<br />
vmware-au 1284 root 11u IPv4 33013 0t0 TCP *:902 (LISTEN)<br />
sshd 8786 root 3u IPv4 114131 0t0 TCP *:22 (LISTEN)<br />
sshd 8786 root 4u IPv6 114133 0t0 TCP *:22 (LISTEN)<br />
cupsd 12124 root 6u IPv6 138503 0t0 TCP [::1]:631 (LISTEN)<br />
cupsd 12124 root 7u IPv4 138504 0t0 TCP 127.0.0.1:631 (LISTEN)<br />
VirtualBo 17065 wwadmin 48u IPv4 185297 0t0 TCP 127.0.0.1:8081 (LISTEN)<br />
VirtualBo 17065 wwadmin 49u IPv4 185298 0t0 TCP 127.0.0.1:4443 (LISTEN)<br />
VirtualBo 17065 wwadmin 50u IPv4 185299 0t0 TCP 127.0.0.1:8080 (LISTEN)<br />
VirtualBo 17065 wwadmin 51u IPv4 185300 0t0 TCP 127.0.0.1:2222 (LISTEN)<br />
<br />
Notice that port forwarding for VirtualBox has been set up correctly.<br />
<br />
<br />
<br />
-- Main.ArnoldPizer - August 2022 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.17_Ubuntu_Server_22.04_LTS_Virtual_Machine_Image&diff=24172WeBWorK 2.17 Ubuntu Server 22.04 LTS Virtual Machine Image2023-09-11T17:58:44Z<p>Apizer: /* OVA and OVF files */</p>
<hr />
<div><!--<br />
{{UnderConstruction}} <br />
--><br />
<br />
These instructions cover the installation of the Ubuntu Server 22.04 LTS 64 bit operating system and WeBWorK 2.17 using the WeBWorK Virtual Machine Image. <br />
<br />
The WeBWorK Virtual Machine Image is an <code>.ova</code> file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, QEMU/KVM, etc. <br />
<br />
This image file has been tested on <br />
* VMware Workstation 16 Player<br />
* VirtualBox 6<br />
<br />
This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Apache2, MariaDB, R server, log rotation, etc.) installed and configured. <br />
<br />
== Installing from WW2.17 Ubuntu22.04 Server Virtual Machine Image ==<br />
<br />
===Overview===<br />
After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.17, Apache2, MariaDB, R server, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who has sudo privileges), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> who has professor privileges (see below).<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.17 at<br />
[[Installation_Manual_for_2.17_on_Ubuntu|Installation Manual for 2.17 on Ubuntu]].<br />
<br />
===Download the ova image===<br />
<br />
Download the .sha checksum and the .ova files from the WeBWorK Download Site below. <br />
<br />
You want to download the files <code>WW2.17_Ubuntu22.04_Server.ova.sha</code> and <code>WW2.17_Ubuntu22.04_Server.ova</code><br />
The ova is a 6.3 GB file.<br />
<br />
* [http://webwork.maa.org/ww-downloads/wwdownload.html WeBWorK Download Site]<br />
<br />
Verify the SHA1 checksum of your downloaded file <code>WW2.17_Ubuntu22.04_Server.ova</code> agrees with the one in <code>WW2.17_Ubuntu22.04_Server.ova.sha</code>.<br />
<br />
===OVA and OVF files===<br />
The <code>.ova</code> file is simply a tar bundle containing an <code>.ovf</code> file, one or more <code>.vmdk</code> files, a <code>.mf</code> file and possibly other files.<br />
* The <code>.ovf</code> file is an XML file which describes the packaged virtual machine and is human-readable. <br />
* The <code>.vmdk</code> file(s) contain the disk images(s).<br />
* Possibly other files<br />
* The <code>.mf</code> file contains SHA1 checksums for the above files.<br />
<br />
You can import a virtual machine either from an <code>.ova</code> file or from the <code>.ovf</code>, <code>.vmdk</code>, <code>.mf</code> collection. Sometimes importing from the <code>.ova</code> file may fail whereas importing from the <code>.ovf</code> or <code>.vmdk</code> file will succeed.<br />
<br />
You can extract the files in <code>WW2.18_Ubuntu22.04_Server.ova</code> with the command <br />
<br />
$ tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
<br />
You then can look at (and possibly edit) the human readable <code>WW2.18_Ubuntu22.04_Server.ofv</code> file. If you do edit the <code>WW2.18_Ubuntu22.04_Server.ofv</code> file, you will also have to compute the new SHA1 checksum and replace the old one in the <code>WW2.18_Ubuntu22.04_Server.mf</code> file for the files to be usable.<br />
<br />
===Installing the WeBWorK Virtual Machine Image ===<br />
<br />
Import the file <code>WW2.17_Ubuntu22.04_Server.ova</code> into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 16 Player <br />
running on a Windows 11 Pro host. It has been tested on <br />
* VMware Workstation 16 Player running on a Windows 11 host (Home and Pro editions)<br />
* VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host<br />
* VirtualBox 6 running on a Windows 11 host (Home and Pro editions)<br />
* VirtualBox 6 running on a Ubuntu 22.04 Desktop host<br />
'''See [[#Specific Virtual Environments|Specific Virtual Environments]] below for installation information on specific virtual environments.'''<br />
<br />
====Processors, Memory, Hard Disk, Networking====<br />
The WeBWorK Virtual Machine Image was created with the following parameters:<br />
*20 GB dynamically allocated disk drive in VMDK format (single file) of which 11 GB is used<br />
*4 GB memory<br />
*2 cpu<br />
These resources are OK for testing and should suffice for small courses but it is possible to overwhelm the machine.<br />
<br />
Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 16 Player running on a Windows 11 host). You should adjust these resources either when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk is more complicated. See [[#Specific Virtual Environments|Specific Virtual Environments]] below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see [[#Increase Disk Space|Increase Disk Space]] below). <br />
<br />
Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]) and/or look at [[#Debugging Networking Issues|Debugging Networking Issues]].<br />
<br />
===Import the .ova file===<br />
There may be specific information for your situation below. See<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
* [[#Amazon EC2|Amazon EC2]]<br />
<br />
===Your server===<br />
After importing, your virtual WeBWorK server will be identical to a system created by following the instructions [[Installation Manual for 2.17 on Ubuntu|Installation Manual for 2.17 on Ubuntu]] with Optional Configurations B and C implemented. '''Note that''' Option A (SSL) is not implemented (see [[#Set up WeBWorK to use SSL|Set up WeBWorK to use SSL]] below).<br />
<br />
'''Note''' that on some virtual environments, you may need to take additional actions. See the section [[#Specific Virtual Environments|Specific Virtual Environments]] below.<br />
<br />
You should read through the instructions [[Installation Manual for 2.17 on Ubuntu|Installation Manual for 2.17 on Ubuntu]] in order to understand how your server has been set up. Especially look at<br />
[[Installation Manual for 2.17 on Ubuntu#Notation|Notation in the Installation Manual for 2.17 on Ubuntu]] to understand the notation we use in these instructions.<br />
<br />
==Boot Your Server==<br />
===Log into your server ===<br />
After booting you should see a login prompt (you may have to press <code>&lt;Enter&gt;</code>).<br />
*Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges. We will denote<br />
wwadmin's password by <code><wwadmin password></code>. Initially this is set to <code>wwadmin</code>.<br />
If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.<br />
<br />
===Test your ip address===<br />
Run the command<br />
$ ip address show<br />
and look at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]). If that doesn't help look at [[#Debugging Networking Issues|Debugging Networking Issues]]. '''You have to fix this before you can go on to the next step'''.<br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program. <br />
<br />
You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with <code>copy</code> from the Edit menu or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit menu list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code> or <code>&lt;Shift&gt; &lt;Insert&gt;</code> depending on your application). <br />
<br />
My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. In any event, after testing, read the section [[#Make the WeBWorK Configuration Permanent|Make the WeBWorK Configuration Permanent]] below. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.<br />
<br />
I am assuming your network has been set up automatically.<br />
<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a <br />
terminal emulator running on your host using ssh, or from the terminal on the guest once you login. <br />
<br />
Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will probably see (in the summer)<br />
...<br />
Time zone: Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/New_York". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/New_York<br />
[sudo] password for wwadmin: <wwadmin password><br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
=== Checking for and Installing Hotfixes ===<br />
Follow the instructions at [[Installation_Manual_for_2.17_on_Ubuntu#Checking_for_and_Installing_Hotfixes|Checking for and Installing Hotfixes in the Installation Manual for 2.17 on Ubuntu]].<br />
<br />
'''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.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the virtual machine image was built. <br />
You should definitely update the webwork2 code.'''<br />
--><br />
<!--<br />
'''Important: The are bug fixes for the pg code that occurred after the virtual machine image was built. You should definitely update the pg code.'''<br />
--><br />
<br />
=== WeBWorK configuration ===<br />
<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
First we have to edit information about the Apache2 server setup. <br />
Search for <code>192.168.138.132</code> and replace that by your the new ip address you found above (<code>192.168.76.128</code> in our example above). <br />
<br />
'''But wait, this can be tricky'''. If you set up port forwarding (as we had to for VirtualBox), then instead use the code<br />
$server_root_url = 'http://localhost';<br />
<br />
The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM)<br />
<br />
$server_root_url = 'http://192.168.76.128';<br />
<br />
where of course your ip address may be different. The "http://" is important. <br />
<br />
'''Remark'''. First of all, let me admit I don't understand the above - it just works. If this is not set correctly (and I don't really understand what "correctly" means), then when you test the Library Browser, e.g. by clicking on <code>Library Browser</code> on the <code>Main Menu</code>, then on <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, you will not be able to select a <code>Chapter</code> and you will see an error message similar to<br />
183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.<br />
If you google this message, you will find a lot of people have seen this error and the most common reason is that <code>$server_root_url</code> has not been set correctly, whatever "correctly" means. A common error is to use forget <code>http://</code> or to use <code>http://</code> when you should use <code>https://</code> (or vice versa) or to just have the wrong domain name or ip address.<br />
<br />
We now continue editing <code>site.conf</code> <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then.<br />
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.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.'''<br />
<br />
Then save the file and Quit.<br />
<br />
==== The defaults.config file ====<br />
<br />
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 <code>defaults.config</code>, you will see the lines<br />
<br />
$mail{allowedRecipients} = [<br />
#'prof1@yourserver.yourdomain.edu',<br />
#'prof2@yourserver.yourdomain.edu',<br />
];<br />
<br />
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.<br />
<br />
==== Edit the localOverrides.conf file ====<br />
Now backup and edit localOverrides.conf 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).<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak1<br />
$ nano localOverrides.conf<br />
<br />
Now add and then edit the lines<br />
<br />
<br />
$mail{allowedRecipients} = [<br />
#'prof1@yourserver.yourdomain.edu',<br />
#'prof2@yourserver.yourdomain.edu',<br />
];<br />
Of course you have to remove the comment character #.<br />
<br />
Then save the file and Quit.<br />
<br />
'''Now restart apache so that our changes to the conf files takes effect.'''<br />
<br />
$ sudo apache2ctl restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
===Set up WeBWorK to use SSL===<br />
This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.<br />
<br />
Follow the instructions at [[Installation_Manual_for_2.17_on_Ubuntu#Implement Option A (SSL)|Implement Option A (SSL) in the Installation Manual for 2.17 on Ubuntu]].<br />
<br />
===Finish up===<br />
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.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://192.168.76.128/webwork2</code> where of course you should use your actual ip address. If you have already set up https and haven't setup the redirect, then you should use <code>https://192.168.76.128/webwork2</code> . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.<br />
<br />
<br />
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 <code>/var/log/apache2/error.log</code>. And you should look at [[Installation_Manual_for_2.17_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.17 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Make the WeBWorK Configuration Permanent==<br />
<br />
Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with <code>ip address show</code>) and used that when editing the <code>site.conf</code> file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.<br />
# The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the <code>site.conf</code> file. <br />
# The other method is to setup networking to use a fixed specific ip address for your server and use that in the <code>site.conf</code> file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the [[#Networking_2|Networking]] section under [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] below for information on editing these files. You can search the web for information on the correct syntax to use.<br />
<br />
Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections [[#Edit the site.conf file|Edit the site.conf file]] and [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]].<br />
<br />
Remember that any time you edit WeBWorK's configuration files, you have the restart Apache2 for the changes to take effect. For networking changes to take effect, you should reboot the server.<br />
<br />
==Passwords==<br />
It is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access.<br />
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.<br />
<br />
====Change the password for wwadmin====<br />
<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$ <br />
'''Do not forget the new <code>&lt;wwadmin password&gt;</code> that you just entered.''' Below when we refer to <wwadmin password>, we mean the '''new''' <wwadmin password>.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = "wwadmin";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. We refer to this password as <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart Apache so the changes take effect.<br />
<br />
$ sudo apache2ctl graceful<br />
[sudo] password for wwadmin: <wwadmin password><br />
$<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,authentication_string,password,plugin,host FROM mysql.user;<br />
<br />
You will see a table with two users (<code>root</code> and <code>webworkWrite</code>). <br />
You should see that both users have a valid password (which will be displayed in encrypted form) and <code>root</code> is authenticated by a socket. <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT Host, User, password FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
Finally a note on the MariaDB root password. In Ubuntu systems running MySQL 5.7 (and later versions), the MariaDBL 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.16_on_Ubuntu#Securing_the_Database]]) we had to set a password for the MariaDB root user and<br />
that password was set to "wwadmin" even though it is not used. If you ever change how the MariaDB root user is authenticated (you shouldn't!!), remember this.<br />
<br />
====Change the password for admin====<br />
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.<br />
<br />
====Change the password for profa====<br />
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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
http://192.168.76.128/webwork2/admin</code> <br />
http://192.168.76.128/webwork2/mytestcourse</code> <br />
where of course you should use your actual ip address.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust Apache's configuration according to your server's memory===<br />
Look at [[Installation_Manual_for_2.17_on_Ubuntu#Edit_mpm_prefork.conf|Edit mpm_prefork.conf in the Installation Manual for 2.17 on Ubuntu ]] and adjust "MaxRequestWorkers"<br />
according to the rule of thumb given there.<br />
<br />
===Set up access to Apache's server-info and servo-status===<br />
<br />
This isn't really necessary but you should look at [[Installation_Manual_for_2.17_on_Ubuntu#enabling_info.conf_and_status.conf_in_Ubuntu|the info.conf and status.conf section in Installation Manual for 2.17 on Ubuntu]].<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in [[#Specific Virtual Environments|Specific Virtual Environments]] below. <br />
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<br />
20 GB to 30GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 19G 11G 7.3G 59% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/sda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 21.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags: <br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 20.0GB 20.0GB ext4<br />
<br />
(parted)<br />
<br />
We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command<br />
(parted) resizepart<br />
Partition number? 2<br />
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [20GB]? 30GB<br />
(parted)<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 31.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags:<br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 30.0GB 30.0GB ext4<br />
<br />
(parted)<br />
Notice we now have a 30 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below<br />
$ sudo resize2fs /dev/sda2<br />
[sudo] password for wwadmin: <wwadmin password><br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/sda2 is mounted on /; on-line resizing required<br />
old_desc_blocks = 2, new_desc_blocks = 3<br />
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 29G 11G 18G 38% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
*'''Option A''' is not implemented. '''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
==Specific Virtual Environments==<br />
Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of<br />
the specific environments we have information on:<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 15 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
<br />
===VMware Workstation 16 Player running on a Windows 11 host===<br />
====Importing the ova File====<br />
For VMware Player select Player, File, Open and then browse to the location of the <code>WW2.17_Ubuntu22.04_Server.ova</code> file and open the file.<br />
Name your machine and select a storage path and then hit Import<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
====Accessing your server from your host====<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the '''WeBWorK''' Welcome page. <br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 6 running on a Windows 11 host===<br />
<br />
====Importing the ova File====<br />
For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the <code>WW2.17_Ubuntu22.04_Server.ova</code> file and open the file. Click Next, and then Import. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Initially networking will be broken. Do the following from your guest WeBWorK system<br />
$ sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
...<br />
logical name: enp0s17<br />
version: 02<br />
serial: 08:00:27:30:28:b6<br />
...<br />
Remember the logical name from your system as we will need it below. We have to backup and then edit one file.<br />
<br />
$ cd /etc/netplan/<br />
$ sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak1<br />
[sudo] password for wwadmin: <wwadmin password> <br />
Now edit the <code> 00-installer-config.yaml</code> file<br />
$ sudo nano 00-installer-config.yaml<br />
It should look like (I had to stretch the window to see the whole file):<br />
# This is the network config written by 'subiquity'<br />
network:<br />
ethernets:<br />
ens33:<br />
dhcp4: true<br />
version: 2<br />
Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.<br />
<br />
<br />
Now reboot your server,e.g.<br />
$ sudo reboot<br />
[sudo] password for wwadmin: <wwadmin password> <br />
login and run the command<br />
$ ip address show<br />
and look at the output, something like<br />
... <br />
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000<br />
link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff<br />
inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17<br />
...<br />
<br />
We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below. <br />
<br />
In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network"<br />
Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:<br />
<br />
{| class="wikitable"<br />
|+Port Forwarding<br />
!Name<br />
!Protocol<br />
!Host IP<br />
!Host Port<br />
!Guest IP<br />
!Guest Port<br />
|-<br />
|ssh<br />
|TCP<br />
|127.0.0.1<br />
|2222<br />
|10.0.2.15<br />
|22<br />
|-<br />
|https<br />
|TCP<br />
|127.0.0.1<br />
|4443<br />
|10.0.2.15<br />
|443<br />
|-<br />
|http<br />
|TCP<br />
|127.0.0.1<br />
|8081<br />
|10.0.2.15<br />
|80<br />
|}<br />
Double check that you have entered everything correctly ('''using''' your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".<br />
<br />
Now boot your server.<br />
<br />
====Accessing your server from your host====<br />
We need to employ the port forwarding rules above.<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up with the port forwarding rules above, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and you should the '''WeBWorK''' Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.<br />
<br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your guest id shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list <br />
(probably "WW2.17_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. <br />
Click “Apply” when you're done.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host===<br />
<br />
====Importing the ova File====<br />
For VMware Player select File, Open a Virtual Machine and then browse to the location of the <code>WW2.17_Ubuntu22.04_Server.ova</code> file and import the file.<br />
<br />
You may get a warning message but on retry it will work (strange since the ova image was created on VMware Player).<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
Accessing your server is exactly the same as in [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]] above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.76.128<br />
where of course you need to use the ip address of your WeBWorK guest server.<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 6 running on a Ubuntu 22.04 Desktop host===<br />
====Importing the ova File====<br />
Importing the ova File is exactly the same as in [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Accessing your server involves the same procedure as in [[#VirtualBox 6 running on a Windows 101 host|VirtualBox 6 running on a Windows 11 host]] above. So you have to<br />
# Find the name and MAC address of the virtual nic (network interface card)<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
# Set up port forwarding<br />
See [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above for details.<br />
<br />
'''Except''' that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh -p 2222 wwadmin@127.0.0.1<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
The procedure is the same as in [[#Expand the disk drive_2|Expand the disk drive]] the Windows 11 case above.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===QEMU/KVM running on a Ubuntu 22.04 Desktop host===<br />
The procedure should be very similar to that documented in<br />
[[Installing_from_WW2.15_Ubuntu20.04_Server_Virtual_Machine_Image#QEMU.2FKVM_running_on_a_Ubuntu_20.04_Desktop_host]]<br />
except that the <code>virt-convert</code> program no longer seems to be contained in the standard Ubuntu 22.04 repositories and you will have to find it or an alternative. We have not tested the ova on KVM.<br />
<br />
===Amazon EC2===<br />
While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the [[WeBWorK_2.17_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image]] is faster and easier anyway.<br />
<br />
==Debugging Networking Issues==<br />
If after reading the information above on networking you are still having problems, maybe the information below will be of help.<br />
<br />
===One method===<br />
There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms:<br />
$ ip address show<br />
does not return an ip address and the WW guest can not access the outside world.<br />
<br />
In VirtualBox I built another guest from the <code>ubuntu-22.04-live-server-amd64.iso</code> using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by<br />
sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files<br />
/etc/netplan/00-installer-config.yaml<br />
and<br />
/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg<br />
BUT in the WW guest the information did not agree. This led to the information given in [[#Networking_2|the Networking section of VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
===Ports on your WeBWorK guest===<br />
Run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you see something like<br />
<br />
systemd-r 697 systemd-resolve 13u IPv4 19596 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
sshd 772 root 3u IPv4 21834 0t0 TCP *:22 (LISTEN)<br />
sshd 772 root 4u IPv6 21845 0t0 TCP *:22 (LISTEN)<br />
lighttpd 810 www-data 4u IPv4 22509 0t0 TCP *:8080 (LISTEN)<br />
mysqld 856 mysql 31u IPv6 23312 0t0 TCP *:33060 (LISTEN)<br />
mysqld 856 mysql 33u IPv4 23654 0t0 TCP 127.0.0.1:3306 (LISTEN)<br />
Rserve 865 rserveuser 3u IPv4 22878 0t0 TCP 127.0.0.1:6311 (LISTEN)<br />
/usr/sbin 946 root 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 956 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 957 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 958 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 959 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 960 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
<br />
===Ports on your Windows 11 Pro host===<br />
Open a Power Shell command window as an administrator and run the command (it can take awhile)<br />
PS C:\> netstat -ab<br />
<br />
Active Connections<br />
<br />
Proto Local Address Foreign Address State<br />
TCP 0.0.0.0:135 desktop:0 LISTENING<br />
RpcSs<br />
[svchost.exe]<br />
TCP 0.0.0.0:443 desktop:0 LISTENING<br />
[vmware-hostd.exe]<br />
TCP 0.0.0.0:445 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:903 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:913 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:2869 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:3306 desktop:0 LISTENING<br />
[mysqld.exe]<br />
...<br />
TCP 0.0.0.0:6000 desktop:0 LISTENING<br />
[XWin_MobaX.exe]<br />
TCP 0.0.0.0:49664 desktop:0 LISTENING<br />
...<br />
TCP 127.0.0.1:2222 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52916 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52917 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:4443 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
...<br />
<br />
===Ports on your Linux host===<br />
<br />
Run the command<br />
<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for ****: <br />
<br />
and you should see something like the following<br />
systemd-r 436 systemd-resolve 13u IPv4 18620 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
vmware-au 1284 root 10u IPv6 33012 0t0 TCP *:902 (LISTEN)<br />
vmware-au 1284 root 11u IPv4 33013 0t0 TCP *:902 (LISTEN)<br />
sshd 8786 root 3u IPv4 114131 0t0 TCP *:22 (LISTEN)<br />
sshd 8786 root 4u IPv6 114133 0t0 TCP *:22 (LISTEN)<br />
cupsd 12124 root 6u IPv6 138503 0t0 TCP [::1]:631 (LISTEN)<br />
cupsd 12124 root 7u IPv4 138504 0t0 TCP 127.0.0.1:631 (LISTEN)<br />
VirtualBo 17065 wwadmin 48u IPv4 185297 0t0 TCP 127.0.0.1:8081 (LISTEN)<br />
VirtualBo 17065 wwadmin 49u IPv4 185298 0t0 TCP 127.0.0.1:4443 (LISTEN)<br />
VirtualBo 17065 wwadmin 50u IPv4 185299 0t0 TCP 127.0.0.1:8080 (LISTEN)<br />
VirtualBo 17065 wwadmin 51u IPv4 185300 0t0 TCP 127.0.0.1:2222 (LISTEN)<br />
<br />
Notice that port forwarding for VirtualBox has been set up correctly.<br />
<br />
<br />
<br />
-- Main.ArnoldPizer - August 2022 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Virtual_Machine_Image&diff=24171WeBWorK 2.18 Ubuntu Server 22.04 LTS Virtual Machine Image2023-09-11T17:54:54Z<p>Apizer: </p>
<hr />
<div><!--<br />
{{UnderConstruction}} <br />
--><br />
<br />
These instructions cover the installation of the Ubuntu Server 22.04 LTS 64 bit operating system and WeBWorK 2.18 using the WeBWorK Virtual Machine Image. <br />
<br />
The WeBWorK Virtual Machine Image is an <code>.ova</code> file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, QEMU/KVM, etc. <br />
<br />
This image file has been tested on <br />
* VMware Workstation 17 Player<br />
* VirtualBox 7<br />
* QEMU/KVM running on a Ubuntu 22.04 Desktop host<br />
<br />
This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc.) installed and configured. <br />
<br />
== Installing from WW2.18 Ubuntu22.04 Server Virtual Machine Image ==<br />
<br />
===Overview===<br />
After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who has sudo privileges), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> who has professor privileges and also the Mjolicious secret (see below).<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]].<br />
<br />
===Download the ova image===<br />
<br />
Download the sha256 checksum and the .ova files from the WeBWorK Download Site below. <br />
<br />
You want to download the files <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code> and <code>WW2.18_Ubuntu22.04_Server.ova</code><br />
The ova is a 7.3 GB file.<br />
<br />
* [http://webwork.maa.org/ww-downloads/wwdownload.html WeBWorK Download Site]<br />
<br />
Verify the SHA256 checksum of your downloaded file <code>WW2.18_Ubuntu22.04_Server.ova</code> agrees with the one in <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code>.<br />
<br />
===OVA and OVF files===<br />
The <code>.ova</code> file is simply a tar bundle containing an <code>.ovf</code> file, one or more <code>.vmdk</code> files, a <code>.mf</code> file and possibly other files.<br />
* The <code>.ovf</code> file is an XML file which describes the packaged virtual machine and is human-readable. <br />
* The <code>.vmdk</code> file(s) contain the disk images(s).<br />
* Possibly other files<br />
* The <code>.mf</code> file contains SHA1 checksums for the above files.<br />
<br />
You can import a virtual machine either from an <code>.ova</code> file or from the <code>.ovf</code>, <code>.vmdk</code>, <code>.mf</code> collection. Sometimes importing from the <code>.ova</code> file may fail whereas importing from the <code>.ovf</code> or <code>.vmdk</code> file will succeed.<br />
<br />
You can extract the files in <code>WW2.18_Ubuntu22.04_Server.ova</code> with the command <br />
<br />
$ tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
<br />
You then can look at (and possibly edit) the human readable <code>WW2.18_Ubuntu22.04_Server.ofv</code> file. If you do edit the <code>WW2.18_Ubuntu22.04_Server.ofv</code> file, you will also have to compute the new SHA1 checksum and replace the old one in the <code>WW2.18_Ubuntu22.04_Server.mf</code> file for the files to be usable.<br />
<br />
===Installing the WeBWorK Virtual Machine Image ===<br />
<br />
Import the file <code>WW2.18_Ubuntu22.04_Server.ova</code> into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 17 Player <br />
running on a Windows 11 Pro host. It has been tested on <br />
* VMware Workstation 17 Player running on a Windows 11 host (Pro edition)<br />
* VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host<br />
* VirtualBox 7 running on a Windows 11 host (Home and Pro editions)<br />
* VirtualBox 6 running on a Ubuntu 22.04 Desktop host<br />
'''See [[#Specific Virtual Environments|Specific Virtual Environments]] below for installation information on specific virtual environments.'''<br />
<br />
====Processors, Memory, Hard Disk, Networking====<br />
The WeBWorK Virtual Machine Image was created with the following parameters:<br />
*20 GB dynamically allocated disk drive in VMDK format (single file) of which 13 GB is used<br />
*4 GB memory<br />
*2 cpu<br />
These resources are OK for testing and may suffice for a very small course but it is possible to overwhelm the machine. <br />
<br />
Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 17 Player running on a Windows 11 host). You should adjust these resources either when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk is more complicated. See [[#Specific Virtual Environments|Specific Virtual Environments]] below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see [[#Increase Disk Space|Increase Disk Space]] below). <br />
<br />
Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]) and/or look at [[#Debugging Networking Issues|Debugging Networking Issues]].<br />
<br />
===Import the .ova file===<br />
There may be specific information for your situation below. See<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
* [[#Amazon EC2|Amazon EC2]]<br />
<br />
===Your server===<br />
After importing, your virtual WeBWorK server will be identical to a system created by following the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] with the Webwork2 Mojolicious App being served directly via hypnotoad (option 1) and the Optional Configurations B and C implemented. '''Note that''' Option A (SSL) is not implemented (see [[#Set up WeBWorK to use SSL|Set up WeBWorK to use SSL]] below).<br />
<br />
'''Note''' that on some virtual environments, you may need to take additional actions. See the section [[#Specific Virtual Environments|Specific Virtual Environments]] below.<br />
<br />
You should read through the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] in order to understand how your server has been set up. Especially look at<br />
[[Installation Manual for 2.18 on Ubuntu#Notation|Notation in the Installation Manual for 2.18 on Ubuntu]] to understand the notation we use in these instructions.<br />
<br />
==Boot Your Server==<br />
===Log into your server ===<br />
After booting you should see a login prompt (you may have to press <code>&lt;Enter&gt;</code>).<br />
*Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges. We will denote<br />
wwadmin's password by <code><wwadmin password></code>. Initially this is set to <code>wwadmin</code>.<br />
If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.<br />
<br />
===Test your ip address===<br />
Run the command<br />
$ ip address show<br />
and look at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]). If that doesn't help look at [[#Debugging Networking Issues|Debugging Networking Issues]]. '''You have to fix this before you can go on to the next step'''.<br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program. <br />
<br />
You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with <code>copy</code> from the Edit menu or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit menu list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code> or <code>&lt;Shift&gt; &lt;Insert&gt;</code> depending on your application). <br />
<br />
My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. In any event, after testing, read the section [[#Make the WeBWorK Configuration Permanent|Make the WeBWorK Configuration Permanent]] below. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.<br />
<br />
I am assuming your network has been set up automatically.<br />
<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a <br />
terminal emulator running on your host using ssh, or from the terminal on the guest once you login. <br />
<br />
Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will probably see <br />
...<br />
Time zone: Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/New_York". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/New_York<br />
[sudo] password for wwadmin: <wwadmin password><br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
=== Checking for and Installing Hotfixes ===<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check_for_and_Install_Hotfixes in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
'''Important: The are bug fixes for both the webwork2 code and the pg code that occurred after the virtual machine image was built. You should definitely update both the webwork2 and pg code.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the virtual machine image was built. <br />
You should definitely update the webwork2 code.'''<br />
--><br />
<!--<br />
'''Important: The are bug fixes for the pg code that occurred after the virtual machine image was built. You should definitely update the pg code.'''<br />
--><br />
<br />
=== WeBWorK configuration ===<br />
<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
First we have to edit information about the network server setup. <br />
Search for <code>192.168.138.131</code> and replace that by your the new ip address you found above (<code>192.168.76.128</code> in our example above). <br />
<br />
'''But wait, this can be tricky'''. If you set up port forwarding (as we had to for VirtualBox), then instead use the code<br />
$server_root_url = 'http://localhost';<br />
<br />
The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM)<br />
<br />
$server_root_url = 'http://192.168.76.128';<br />
<br />
where of course your ip address may be different. The "http://" is important. <br />
<br />
'''Remark'''. First of all, let me admit I don't understand the above - it just works. If this is not set correctly (and I don't really understand what "correctly" means), then when you test the Library Browser, e.g. by clicking on <code>Library Browser</code> on the <code>Main Menu</code>, then on <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, you will not be able to select a <code>Chapter</code> and you will see an error message similar to<br />
183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.<br />
If you google this message, you will find a lot of people have seen this error and the most common reason is that <code>$server_root_url</code> has not been set correctly, whatever "correctly" means. A common error is to forget <code>http://</code> or to use <code>http://</code> when you should use <code>https://</code> (or vice versa) or to just have the wrong domain name or ip address.<br />
<br />
We now continue editing <code>site.conf</code> <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then.<br />
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.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.'''<br />
<br />
Then save the file and Quit. And restart the webwork2 app so that these changes take effect:<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
===Set up WeBWorK to use SSL===<br />
This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.<br />
<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Implement Option A (SSL)|Implement Option A (SSL) in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
Note that the Virtual Machine Image was built using Option 1: Serving Directly via Hypnotoad so that in the instructions for setting up SSL follow the section<br />
Set up Hypnotoad to use SSL (Option 1).<br />
<br />
===Finish up===<br />
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.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://192.168.76.128/webwork2</code> where of course you should use your actual ip address. If you have already set up https and haven't setup the redirect, then you should use <code>https://192.168.76.128/webwork2</code> . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.<br />
<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Make the WeBWorK Configuration Permanent==<br />
<br />
Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with <code>ip address show</code>) and used that when editing the <code>site.conf</code> file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.<br />
# The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the <code>site.conf</code> file. <br />
# The other method is to setup networking to use a fixed specific ip address for your server and use that in the <code>site.conf</code> file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the [[#Networking_2|Networking]] section under [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] below for information on editing these files. You can search the web for information on the correct syntax to use.<br />
<br />
Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections [[#Edit the site.conf file|Edit the site.conf file]] and [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]].<br />
<br />
Remember that any time you edit WeBWorK's configuration files, you have the restart the WeBWorK2 app for the changes to take effect; see [[Installation_Manual_for_2.18_on_Ubuntu#Enable_and_start_the_Webwork2_Systemd_Service|Enable_and_start_the_Webwork2_Systemd_Service in the Installation Manual for 2.18 on Ubuntu]]. For networking changes to take effect, you should reboot the server.<br />
<br />
==Passwords==<br />
It is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access.<br />
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. Also change the mojolicious.yml secret.<br />
====Change the mojolicious.yml secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
====Change the password for wwadmin====<br />
<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$ <br />
'''Do not forget the new <code>&lt;wwadmin password&gt;</code> that you just entered.''' Below when we refer to <wwadmin password>, we mean the '''new''' <wwadmin password>.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = "wwadmin";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. We refer to this password as <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart webwork2 so the changes take effect.<br />
<br />
$ sudo systemctl restart webwork2<br />
[sudo] password for wwadmin: <wwadmin password><br />
$<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,authentication_string,password,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <code>webworkWrite</code> should have <br />
a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT Host, User, password FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
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.<br />
<br />
====Change the password for profa====<br />
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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
http://192.168.76.128/webwork2/admin</code> <br />
http://192.168.76.128/webwork2/mytestcourse</code> <br />
where of course you should use your actual ip address.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust the mojolicious.yml configuration according to your server's memory===<br />
Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. <br />
Search for the lines<br />
clients: 1<br />
workers: 10<br />
spare: 5<br />
and edit the numbers depending on the amount of RAM available on your server. Look at the recommendations for these settings in the section immediately above these lines in the webwork2.mojolicious.yml file<br />
<br />
Then save the file and Quit.<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in [[#Specific Virtual Environments|Specific Virtual Environments]] below. <br />
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<br />
20 GB to 30GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 19G 11G 7.3G 59% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/sda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 21.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags: <br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 20.0GB 20.0GB ext4<br />
<br />
(parted)<br />
<br />
We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command<br />
(parted) resizepart<br />
Partition number? 2<br />
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [20GB]? 30GB<br />
(parted)<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 31.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags:<br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 30.0GB 30.0GB ext4<br />
<br />
(parted)<br />
Notice we now have a 30 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below<br />
$ sudo resize2fs /dev/sda2<br />
[sudo] password for wwadmin: <wwadmin password><br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/sda2 is mounted on /; on-line resizing required<br />
old_desc_blocks = 2, new_desc_blocks = 3<br />
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 29G 11G 18G 38% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
*'''Option A''' is not implemented. '''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
==Specific Virtual Environments==<br />
Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of<br />
the specific environments we have information on:<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 15 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
<br />
===VMware Workstation 17 Player running on a Windows 11 host===<br />
====Importing the ova File====<br />
For VMware Player select Player, File, Open and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file.<br />
Name your machine and select a storage path and then hit Import<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
====Accessing your server from your host====<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the '''WeBWorK Placeholder Page'''. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the '''WeBWorK''' Welcome page. <br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 17 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Windows 11 host===<br />
<br />
====Importing the ova File====<br />
For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file. Click Finish. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Initially networking will be broken. Do the following from your guest WeBWorK system<br />
$ sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
...<br />
logical name: enp0s17<br />
version: 02<br />
serial: 08:00:27:30:28:b6<br />
...<br />
Remember the logical name from your system as we will need it below. We have to backup and then edit one file.<br />
<br />
$ cd /etc/netplan/<br />
$ sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak1<br />
[sudo] password for wwadmin: <wwadmin password> <br />
Now edit the <code> 00-installer-config.yaml</code> file<br />
$ sudo nano 00-installer-config.yaml<br />
It should look like (I had to stretch the window to see the whole file):<br />
# This is the network config written by 'subiquity'<br />
network:<br />
ethernets:<br />
ens33:<br />
dhcp4: true<br />
version: 2<br />
Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.<br />
<br />
<br />
Now reboot your server,e.g.<br />
$ sudo reboot<br />
[sudo] password for wwadmin: <wwadmin password> <br />
login and run the command<br />
$ ip address show<br />
and look at the output, something like<br />
... <br />
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000<br />
link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff<br />
inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17<br />
...<br />
<br />
We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below. <br />
<br />
In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network"<br />
Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:<br />
<br />
{| class="wikitable"<br />
|+Port Forwarding<br />
!Name<br />
!Protocol<br />
!Host IP<br />
!Host Port<br />
!Guest IP<br />
!Guest Port<br />
|-<br />
|ssh<br />
|TCP<br />
|127.0.0.1<br />
|2222<br />
|10.0.2.15<br />
|22<br />
|-<br />
|https<br />
|TCP<br />
|127.0.0.1<br />
|4443<br />
|10.0.2.15<br />
|443<br />
|-<br />
|http<br />
|TCP<br />
|127.0.0.1<br />
|8081<br />
|10.0.2.15<br />
|80<br />
|}<br />
Double check that you have entered everything correctly ('''using''' your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".<br />
<br />
Now boot your server.<br />
<br />
====Accessing your server from your host====<br />
We need to employ the port forwarding rules above.<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up with the port forwarding rules above, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and you should the '''WeBWorK''' Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.<br />
<br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your guest is shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list <br />
(probably "WW2.18_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. <br />
Click “Apply” when you're done.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host===<br />
<br />
====Importing the ova File====<br />
For VMware Player select File, Open a Virtual Machine and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and import the file.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
Accessing your server is exactly the same as in [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]] above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.76.128<br />
where of course you need to use the ip address of your WeBWorK guest server.<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Ubuntu 22.04 Desktop host===<br />
====Importing the ova File====<br />
Importing the ova File is exactly the same as in [[#VirtualBox 76 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card)<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
# Set up port forwarding<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details.<br />
<br />
'''Except''' that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh -p 2222 wwadmin@127.0.0.1<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
The procedure is the same as in [[#Expand the disk drive_2|Expand the disk drive]] the Windows 11 case above.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===QEMU/KVM running on a Ubuntu 22.04 Desktop host===<br />
====First install Qemu-KVM====<br />
<br />
It is probably a good idea to first update and upgrade the system packages:<br />
$ sudo apt update<br />
$ sudo apt upgrade<br />
<br />
Now install Qemu-KVM<br />
$ sudo apt install -y qemu-kvm virt-manager libvirt-daemon-system virtinst libvirt-clients bridge-utils<br />
<br />
Enable and start libvirtd<br />
$ sudo systemctl enable --now libvirtd<br />
$ sudo systemctl start libvirtd<br />
and check that all is OK<br />
$ sudo systemctl status libvirtd<br />
<br />
Now add wwadmin to the kvm and libvirt groups.<br />
$ sudo usermod -aG kvm $USER<br />
$ sudo usermod -aG libvirt $USER<br />
<br />
====Convert the image to qcow2 format====<br />
<br />
cd to whatever directory you downloaded the <code>WW2.18_Ubuntu22.04_Server.ova</code> file to (maybe "Downloads") and then untar it<br />
tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
which might take awhile. Then run the command to covert the vmdk format to qcow2 format<br />
qemu-img convert -p -f vmdk -O qcow2 WW2.18_Ubuntu22.04_Server-disk1.vmdk WW2.18_Ubuntu22.04_Server.qcow2<br />
and move the qcow2 image to the correct location<br />
sudo mv WW2.18_Ubuntu22.04_Server.qcow2 /var/lib/libvirt/images/<br />
<br />
====Boot up your virtual machine====<br />
Start up Virtual Machine Manager (search for VM in the app manager). Note that if you run into problems running the Virtual Machine Manager (e.g. QEMU/KVM not connected), the first thing to try is rebooting your host machine.<br />
<br />
In the Virtual Machine Manager,<br />
select File, New Virtual Machine, Import existing disk image, Forward, Browse and finally select WW2.18_Ubuntu22.04_Server.qcow2. The select Choose Volume and enter Ubuntu 22.04 LTS for the operating system you are installing. Next click Forward and choose your memory and CPUs. Select Forward again, name your system and finally select finish.<br />
<br />
Now log into your virtual machine (wwadmin with password wwadmin)<br />
<br />
====Networking====<br />
<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card), probably something like enp1s0<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details '''except that'''<br />
# You do not need port forwarding<br />
# Instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.122.233<br />
(where of course you need to use the actual ip address of your guest WeBWorK server).<br />
<br />
====Expand the disk drive====<br />
You can do most of this from the graphical Virtual Machine Manager (select the machine, then Edit, Virtual Machine Details). Below are commands to this from the command line. I think you have to actually expand the disk from the command line but you can get information and add cpu's and/or memory from the graphical Virtual Machine Manager.<br />
<br />
I'm assume the name of your WeBWorK guest is <code>wwserver</code> and it is Shutoff. First find the location of the disk.<br />
Run the command<br />
$ sudo virsh domblklist wwserver<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
Target Source<br />
-------------------------------------------------------------------------<br />
sda /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
<br />
Now get some info about the disk<br />
$ sudo qemu-img info /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
image: /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
file format: qcow2<br />
virtual size: 12 GiB (12884901888 bytes)<br />
disk size: 6.76 GiB<br />
cluster_size: 65536<br />
Format specific information:<br />
compat: 1.1<br />
lazy refcounts: false<br />
refcount bits: 16<br />
corrupt: false<br />
<br />
and now lets resize it to 20 GB by adding 8 GB<br />
sudo qemu-img resize /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2 +8G<br />
[sudo] password for wwadmin: <wwadmin password><br />
Image resized.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===Amazon EC2===<br />
While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the [[WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image]] is faster and easier anyway.<br />
<br />
==Debugging Networking Issues==<br />
If after reading the information above on networking you are still having problems, maybe the information below will be of help.<br />
<br />
===One method===<br />
There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms:<br />
$ ip address show<br />
does not return an ip address and the WW guest can not access the outside world.<br />
<br />
In VirtualBox I built another guest from the <code>ubuntu-22.04-live-server-amd64.iso</code> using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by<br />
sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files<br />
/etc/netplan/00-installer-config.yaml<br />
and<br />
/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg<br />
BUT in the WW guest the information did not agree. This led to the information given in [[#Networking_2|the Networking section of VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
===Ports on your WeBWorK guest===<br />
Run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you see something like<br />
<br />
systemd-r 697 systemd-resolve 13u IPv4 19596 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
sshd 772 root 3u IPv4 21834 0t0 TCP *:22 (LISTEN)<br />
sshd 772 root 4u IPv6 21845 0t0 TCP *:22 (LISTEN)<br />
lighttpd 810 www-data 4u IPv4 22509 0t0 TCP *:8080 (LISTEN)<br />
mysqld 856 mysql 31u IPv6 23312 0t0 TCP *:33060 (LISTEN)<br />
mysqld 856 mysql 33u IPv4 23654 0t0 TCP 127.0.0.1:3306 (LISTEN)<br />
Rserve 865 rserveuser 3u IPv4 22878 0t0 TCP 127.0.0.1:6311 (LISTEN)<br />
/usr/sbin 946 root 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 956 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 957 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 958 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 959 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 960 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
<br />
===Ports on your Windows 11 Pro host===<br />
Open a Power Shell command window as an administrator and run the command (it can take awhile)<br />
PS C:\> netstat -ab<br />
<br />
Active Connections<br />
<br />
Proto Local Address Foreign Address State<br />
TCP 0.0.0.0:135 desktop:0 LISTENING<br />
RpcSs<br />
[svchost.exe]<br />
TCP 0.0.0.0:443 desktop:0 LISTENING<br />
[vmware-hostd.exe]<br />
TCP 0.0.0.0:445 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:903 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:913 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:2869 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:3306 desktop:0 LISTENING<br />
[mysqld.exe]<br />
...<br />
TCP 0.0.0.0:6000 desktop:0 LISTENING<br />
[XWin_MobaX.exe]<br />
TCP 0.0.0.0:49664 desktop:0 LISTENING<br />
...<br />
TCP 127.0.0.1:2222 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52916 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52917 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:4443 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
...<br />
<br />
===Ports on your Linux host===<br />
<br />
Run the command<br />
<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for ****: <br />
<br />
and you should see something like the following<br />
systemd-r 436 systemd-resolve 13u IPv4 18620 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
vmware-au 1284 root 10u IPv6 33012 0t0 TCP *:902 (LISTEN)<br />
vmware-au 1284 root 11u IPv4 33013 0t0 TCP *:902 (LISTEN)<br />
sshd 8786 root 3u IPv4 114131 0t0 TCP *:22 (LISTEN)<br />
sshd 8786 root 4u IPv6 114133 0t0 TCP *:22 (LISTEN)<br />
cupsd 12124 root 6u IPv6 138503 0t0 TCP [::1]:631 (LISTEN)<br />
cupsd 12124 root 7u IPv4 138504 0t0 TCP 127.0.0.1:631 (LISTEN)<br />
VirtualBo 17065 wwadmin 48u IPv4 185297 0t0 TCP 127.0.0.1:8081 (LISTEN)<br />
VirtualBo 17065 wwadmin 49u IPv4 185298 0t0 TCP 127.0.0.1:4443 (LISTEN)<br />
VirtualBo 17065 wwadmin 50u IPv4 185299 0t0 TCP 127.0.0.1:8080 (LISTEN)<br />
VirtualBo 17065 wwadmin 51u IPv4 185300 0t0 TCP 127.0.0.1:2222 (LISTEN)<br />
<br />
Notice that port forwarding for VirtualBox has been set up correctly.<br />
<br />
<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Virtual_Machine_Image&diff=24170WeBWorK 2.18 Ubuntu Server 22.04 LTS Virtual Machine Image2023-09-11T17:53:45Z<p>Apizer: </p>
<hr />
<div><!--<br />
{{UnderConstruction}} <br />
--><br />
<br />
These instructions cover the installation of the Ubuntu Server 22.04 LTS 64 bit operating system and WeBWorK 2.18 using the WeBWorK Virtual Machine Image. <br />
<br />
The WeBWorK Virtual Machine Image is an <code>.ova</code> file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, QEMU/KVM, etc. <br />
<br />
This image file has been tested on <br />
* VMware Workstation 17 Player<br />
* VirtualBox 7<br />
<br />
This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc.) installed and configured. <br />
<br />
== Installing from WW2.18 Ubuntu22.04 Server Virtual Machine Image ==<br />
<br />
===Overview===<br />
After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who has sudo privileges), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> who has professor privileges and also the Mjolicious secret (see below).<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]].<br />
<br />
===Download the ova image===<br />
<br />
Download the sha256 checksum and the .ova files from the WeBWorK Download Site below. <br />
<br />
You want to download the files <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code> and <code>WW2.18_Ubuntu22.04_Server.ova</code><br />
The ova is a 7.3 GB file.<br />
<br />
* [http://webwork.maa.org/ww-downloads/wwdownload.html WeBWorK Download Site]<br />
<br />
Verify the SHA256 checksum of your downloaded file <code>WW2.18_Ubuntu22.04_Server.ova</code> agrees with the one in <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code>.<br />
<br />
===OVA and OVF files===<br />
The <code>.ova</code> file is simply a tar bundle containing an <code>.ovf</code> file, one or more <code>.vmdk</code> files, a <code>.mf</code> file and possibly other files.<br />
* The <code>.ovf</code> file is an XML file which describes the packaged virtual machine and is human-readable. <br />
* The <code>.vmdk</code> file(s) contain the disk images(s).<br />
* Possibly other files<br />
* The <code>.mf</code> file contains SHA1 checksums for the above files.<br />
<br />
You can import a virtual machine either from an <code>.ova</code> file or from the <code>.ovf</code>, <code>.vmdk</code>, <code>.mf</code> collection. Sometimes importing from the <code>.ova</code> file may fail whereas importing from the <code>.ovf</code> or <code>.vmdk</code> file will succeed.<br />
<br />
You can extract the files in <code>WW2.18_Ubuntu22.04_Server.ova</code> with the command <br />
<br />
$ tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
<br />
You then can look at (and possibly edit) the human readable <code>WW2.18_Ubuntu22.04_Server.ofv</code> file. If you do edit the <code>WW2.18_Ubuntu22.04_Server.ofv</code> file, you will also have to compute the new SHA1 checksum and replace the old one in the <code>WW2.18_Ubuntu22.04_Server.mf</code> file for the files to be usable.<br />
<br />
===Installing the WeBWorK Virtual Machine Image ===<br />
<br />
Import the file <code>WW2.18_Ubuntu22.04_Server.ova</code> into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 17 Player <br />
running on a Windows 11 Pro host. It has been tested on <br />
* VMware Workstation 17 Player running on a Windows 11 host (Pro edition)<br />
* VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host<br />
* VirtualBox 7 running on a Windows 11 host (Home and Pro editions)<br />
* VirtualBox 6 running on a Ubuntu 22.04 Desktop host<br />
'''See [[#Specific Virtual Environments|Specific Virtual Environments]] below for installation information on specific virtual environments.'''<br />
<br />
====Processors, Memory, Hard Disk, Networking====<br />
The WeBWorK Virtual Machine Image was created with the following parameters:<br />
*20 GB dynamically allocated disk drive in VMDK format (single file) of which 13 GB is used<br />
*4 GB memory<br />
*2 cpu<br />
These resources are OK for testing and may suffice for a very small course but it is possible to overwhelm the machine. <br />
<br />
Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 17 Player running on a Windows 11 host). You should adjust these resources either when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk is more complicated. See [[#Specific Virtual Environments|Specific Virtual Environments]] below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see [[#Increase Disk Space|Increase Disk Space]] below). <br />
<br />
Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]) and/or look at [[#Debugging Networking Issues|Debugging Networking Issues]].<br />
<br />
===Import the .ova file===<br />
There may be specific information for your situation below. See<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
* [[#Amazon EC2|Amazon EC2]]<br />
<br />
===Your server===<br />
After importing, your virtual WeBWorK server will be identical to a system created by following the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] with the Webwork2 Mojolicious App being served directly via hypnotoad (option 1) and the Optional Configurations B and C implemented. '''Note that''' Option A (SSL) is not implemented (see [[#Set up WeBWorK to use SSL|Set up WeBWorK to use SSL]] below).<br />
<br />
'''Note''' that on some virtual environments, you may need to take additional actions. See the section [[#Specific Virtual Environments|Specific Virtual Environments]] below.<br />
<br />
You should read through the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] in order to understand how your server has been set up. Especially look at<br />
[[Installation Manual for 2.18 on Ubuntu#Notation|Notation in the Installation Manual for 2.18 on Ubuntu]] to understand the notation we use in these instructions.<br />
<br />
==Boot Your Server==<br />
===Log into your server ===<br />
After booting you should see a login prompt (you may have to press <code>&lt;Enter&gt;</code>).<br />
*Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges. We will denote<br />
wwadmin's password by <code><wwadmin password></code>. Initially this is set to <code>wwadmin</code>.<br />
If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.<br />
<br />
===Test your ip address===<br />
Run the command<br />
$ ip address show<br />
and look at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]). If that doesn't help look at [[#Debugging Networking Issues|Debugging Networking Issues]]. '''You have to fix this before you can go on to the next step'''.<br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program. <br />
<br />
You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with <code>copy</code> from the Edit menu or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit menu list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code> or <code>&lt;Shift&gt; &lt;Insert&gt;</code> depending on your application). <br />
<br />
My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. In any event, after testing, read the section [[#Make the WeBWorK Configuration Permanent|Make the WeBWorK Configuration Permanent]] below. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.<br />
<br />
I am assuming your network has been set up automatically.<br />
<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a <br />
terminal emulator running on your host using ssh, or from the terminal on the guest once you login. <br />
<br />
Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will probably see <br />
...<br />
Time zone: Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/New_York". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/New_York<br />
[sudo] password for wwadmin: <wwadmin password><br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
=== Checking for and Installing Hotfixes ===<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check_for_and_Install_Hotfixes in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
'''Important: The are bug fixes for both the webwork2 code and the pg code that occurred after the virtual machine image was built. You should definitely update both the webwork2 and pg code.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the virtual machine image was built. <br />
You should definitely update the webwork2 code.'''<br />
--><br />
<!--<br />
'''Important: The are bug fixes for the pg code that occurred after the virtual machine image was built. You should definitely update the pg code.'''<br />
--><br />
<br />
=== WeBWorK configuration ===<br />
<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
First we have to edit information about the network server setup. <br />
Search for <code>192.168.138.131</code> and replace that by your the new ip address you found above (<code>192.168.76.128</code> in our example above). <br />
<br />
'''But wait, this can be tricky'''. If you set up port forwarding (as we had to for VirtualBox), then instead use the code<br />
$server_root_url = 'http://localhost';<br />
<br />
The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM)<br />
<br />
$server_root_url = 'http://192.168.76.128';<br />
<br />
where of course your ip address may be different. The "http://" is important. <br />
<br />
'''Remark'''. First of all, let me admit I don't understand the above - it just works. If this is not set correctly (and I don't really understand what "correctly" means), then when you test the Library Browser, e.g. by clicking on <code>Library Browser</code> on the <code>Main Menu</code>, then on <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, you will not be able to select a <code>Chapter</code> and you will see an error message similar to<br />
183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.<br />
If you google this message, you will find a lot of people have seen this error and the most common reason is that <code>$server_root_url</code> has not been set correctly, whatever "correctly" means. A common error is to forget <code>http://</code> or to use <code>http://</code> when you should use <code>https://</code> (or vice versa) or to just have the wrong domain name or ip address.<br />
<br />
We now continue editing <code>site.conf</code> <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then.<br />
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.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.'''<br />
<br />
Then save the file and Quit. And restart the webwork2 app so that these changes take effect:<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
===Set up WeBWorK to use SSL===<br />
This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.<br />
<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Implement Option A (SSL)|Implement Option A (SSL) in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
Note that the Virtual Machine Image was built using Option 1: Serving Directly via Hypnotoad so that in the instructions for setting up SSL follow the section<br />
Set up Hypnotoad to use SSL (Option 1).<br />
<br />
===Finish up===<br />
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.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://192.168.76.128/webwork2</code> where of course you should use your actual ip address. If you have already set up https and haven't setup the redirect, then you should use <code>https://192.168.76.128/webwork2</code> . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.<br />
<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Make the WeBWorK Configuration Permanent==<br />
<br />
Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with <code>ip address show</code>) and used that when editing the <code>site.conf</code> file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.<br />
# The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the <code>site.conf</code> file. <br />
# The other method is to setup networking to use a fixed specific ip address for your server and use that in the <code>site.conf</code> file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the [[#Networking_2|Networking]] section under [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] below for information on editing these files. You can search the web for information on the correct syntax to use.<br />
<br />
Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections [[#Edit the site.conf file|Edit the site.conf file]] and [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]].<br />
<br />
Remember that any time you edit WeBWorK's configuration files, you have the restart the WeBWorK2 app for the changes to take effect; see [[Installation_Manual_for_2.18_on_Ubuntu#Enable_and_start_the_Webwork2_Systemd_Service|Enable_and_start_the_Webwork2_Systemd_Service in the Installation Manual for 2.18 on Ubuntu]]. For networking changes to take effect, you should reboot the server.<br />
<br />
==Passwords==<br />
It is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access.<br />
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. Also change the mojolicious.yml secret.<br />
====Change the mojolicious.yml secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
====Change the password for wwadmin====<br />
<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$ <br />
'''Do not forget the new <code>&lt;wwadmin password&gt;</code> that you just entered.''' Below when we refer to <wwadmin password>, we mean the '''new''' <wwadmin password>.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = "wwadmin";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. We refer to this password as <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart webwork2 so the changes take effect.<br />
<br />
$ sudo systemctl restart webwork2<br />
[sudo] password for wwadmin: <wwadmin password><br />
$<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,authentication_string,password,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <code>webworkWrite</code> should have <br />
a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT Host, User, password FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
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.<br />
<br />
====Change the password for profa====<br />
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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
http://192.168.76.128/webwork2/admin</code> <br />
http://192.168.76.128/webwork2/mytestcourse</code> <br />
where of course you should use your actual ip address.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust the mojolicious.yml configuration according to your server's memory===<br />
Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. <br />
Search for the lines<br />
clients: 1<br />
workers: 10<br />
spare: 5<br />
and edit the numbers depending on the amount of RAM available on your server. Look at the recommendations for these settings in the section immediately above these lines in the webwork2.mojolicious.yml file<br />
<br />
Then save the file and Quit.<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in [[#Specific Virtual Environments|Specific Virtual Environments]] below. <br />
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<br />
20 GB to 30GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 19G 11G 7.3G 59% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/sda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 21.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags: <br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 20.0GB 20.0GB ext4<br />
<br />
(parted)<br />
<br />
We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command<br />
(parted) resizepart<br />
Partition number? 2<br />
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [20GB]? 30GB<br />
(parted)<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 31.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags:<br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 30.0GB 30.0GB ext4<br />
<br />
(parted)<br />
Notice we now have a 30 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below<br />
$ sudo resize2fs /dev/sda2<br />
[sudo] password for wwadmin: <wwadmin password><br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/sda2 is mounted on /; on-line resizing required<br />
old_desc_blocks = 2, new_desc_blocks = 3<br />
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 29G 11G 18G 38% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
*'''Option A''' is not implemented. '''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
==Specific Virtual Environments==<br />
Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of<br />
the specific environments we have information on:<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 15 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
<br />
===VMware Workstation 17 Player running on a Windows 11 host===<br />
====Importing the ova File====<br />
For VMware Player select Player, File, Open and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file.<br />
Name your machine and select a storage path and then hit Import<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
====Accessing your server from your host====<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the '''WeBWorK Placeholder Page'''. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the '''WeBWorK''' Welcome page. <br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 17 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Windows 11 host===<br />
<br />
====Importing the ova File====<br />
For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file. Click Finish. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Initially networking will be broken. Do the following from your guest WeBWorK system<br />
$ sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
...<br />
logical name: enp0s17<br />
version: 02<br />
serial: 08:00:27:30:28:b6<br />
...<br />
Remember the logical name from your system as we will need it below. We have to backup and then edit one file.<br />
<br />
$ cd /etc/netplan/<br />
$ sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak1<br />
[sudo] password for wwadmin: <wwadmin password> <br />
Now edit the <code> 00-installer-config.yaml</code> file<br />
$ sudo nano 00-installer-config.yaml<br />
It should look like (I had to stretch the window to see the whole file):<br />
# This is the network config written by 'subiquity'<br />
network:<br />
ethernets:<br />
ens33:<br />
dhcp4: true<br />
version: 2<br />
Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.<br />
<br />
<br />
Now reboot your server,e.g.<br />
$ sudo reboot<br />
[sudo] password for wwadmin: <wwadmin password> <br />
login and run the command<br />
$ ip address show<br />
and look at the output, something like<br />
... <br />
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000<br />
link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff<br />
inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17<br />
...<br />
<br />
We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below. <br />
<br />
In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network"<br />
Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:<br />
<br />
{| class="wikitable"<br />
|+Port Forwarding<br />
!Name<br />
!Protocol<br />
!Host IP<br />
!Host Port<br />
!Guest IP<br />
!Guest Port<br />
|-<br />
|ssh<br />
|TCP<br />
|127.0.0.1<br />
|2222<br />
|10.0.2.15<br />
|22<br />
|-<br />
|https<br />
|TCP<br />
|127.0.0.1<br />
|4443<br />
|10.0.2.15<br />
|443<br />
|-<br />
|http<br />
|TCP<br />
|127.0.0.1<br />
|8081<br />
|10.0.2.15<br />
|80<br />
|}<br />
Double check that you have entered everything correctly ('''using''' your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".<br />
<br />
Now boot your server.<br />
<br />
====Accessing your server from your host====<br />
We need to employ the port forwarding rules above.<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up with the port forwarding rules above, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and you should the '''WeBWorK''' Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.<br />
<br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your guest is shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list <br />
(probably "WW2.18_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. <br />
Click “Apply” when you're done.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host===<br />
<br />
====Importing the ova File====<br />
For VMware Player select File, Open a Virtual Machine and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and import the file.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
Accessing your server is exactly the same as in [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]] above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.76.128<br />
where of course you need to use the ip address of your WeBWorK guest server.<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Ubuntu 22.04 Desktop host===<br />
====Importing the ova File====<br />
Importing the ova File is exactly the same as in [[#VirtualBox 76 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card)<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
# Set up port forwarding<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details.<br />
<br />
'''Except''' that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh -p 2222 wwadmin@127.0.0.1<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
The procedure is the same as in [[#Expand the disk drive_2|Expand the disk drive]] the Windows 11 case above.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===QEMU/KVM running on a Ubuntu 22.04 Desktop host===<br />
====First install Qemu-KVM====<br />
<br />
It is probably a good idea to first update and upgrade the system packages:<br />
$ sudo apt update<br />
$ sudo apt upgrade<br />
<br />
Now install Qemu-KVM<br />
$ sudo apt install -y qemu-kvm virt-manager libvirt-daemon-system virtinst libvirt-clients bridge-utils<br />
<br />
Enable and start libvirtd<br />
$ sudo systemctl enable --now libvirtd<br />
$ sudo systemctl start libvirtd<br />
and check that all is OK<br />
$ sudo systemctl status libvirtd<br />
<br />
Now add wwadmin to the kvm and libvirt groups.<br />
$ sudo usermod -aG kvm $USER<br />
$ sudo usermod -aG libvirt $USER<br />
<br />
====Convert the image to qcow2 format====<br />
<br />
cd to whatever directory you downloaded the <code>WW2.18_Ubuntu22.04_Server.ova</code> file to (maybe "Downloads") and then untar it<br />
tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
which might take awhile. Then run the command to covert the vmdk format to qcow2 format<br />
qemu-img convert -p -f vmdk -O qcow2 WW2.18_Ubuntu22.04_Server-disk1.vmdk WW2.18_Ubuntu22.04_Server.qcow2<br />
and move the qcow2 image to the correct location<br />
sudo mv WW2.18_Ubuntu22.04_Server.qcow2 /var/lib/libvirt/images/<br />
<br />
====Boot up your virtual machine====<br />
Start up Virtual Machine Manager (search for VM in the app manager). Note that if you run into problems running the Virtual Machine Manager (e.g. QEMU/KVM not connected), the first thing to try is rebooting your host machine.<br />
<br />
In the Virtual Machine Manager,<br />
select File, New Virtual Machine, Import existing disk image, Forward, Browse and finally select WW2.18_Ubuntu22.04_Server.qcow2. The select Choose Volume and enter Ubuntu 22.04 LTS for the operating system you are installing. Next click Forward and choose your memory and CPUs. Select Forward again, name your system and finally select finish.<br />
<br />
Now log into your virtual machine (wwadmin with password wwadmin)<br />
<br />
====Networking====<br />
<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card), probably something like enp1s0<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details '''except that'''<br />
# You do not need port forwarding<br />
# Instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.122.233<br />
(where of course you need to use the actual ip address of your guest WeBWorK server).<br />
<br />
====Expand the disk drive====<br />
You can do most of this from the graphical Virtual Machine Manager (select the machine, then Edit, Virtual Machine Details). Below are commands to this from the command line. I think you have to actually expand the disk from the command line but you can get information and add cpu's and/or memory from the graphical Virtual Machine Manager.<br />
<br />
I'm assume the name of your WeBWorK guest is <code>wwserver</code> and it is Shutoff. First find the location of the disk.<br />
Run the command<br />
$ sudo virsh domblklist wwserver<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
Target Source<br />
-------------------------------------------------------------------------<br />
sda /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
<br />
Now get some info about the disk<br />
$ sudo qemu-img info /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
image: /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
file format: qcow2<br />
virtual size: 12 GiB (12884901888 bytes)<br />
disk size: 6.76 GiB<br />
cluster_size: 65536<br />
Format specific information:<br />
compat: 1.1<br />
lazy refcounts: false<br />
refcount bits: 16<br />
corrupt: false<br />
<br />
and now lets resize it to 20 GB by adding 8 GB<br />
sudo qemu-img resize /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2 +8G<br />
[sudo] password for wwadmin: <wwadmin password><br />
Image resized.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===Amazon EC2===<br />
While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the [[WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image]] is faster and easier anyway.<br />
<br />
==Debugging Networking Issues==<br />
If after reading the information above on networking you are still having problems, maybe the information below will be of help.<br />
<br />
===One method===<br />
There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms:<br />
$ ip address show<br />
does not return an ip address and the WW guest can not access the outside world.<br />
<br />
In VirtualBox I built another guest from the <code>ubuntu-22.04-live-server-amd64.iso</code> using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by<br />
sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files<br />
/etc/netplan/00-installer-config.yaml<br />
and<br />
/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg<br />
BUT in the WW guest the information did not agree. This led to the information given in [[#Networking_2|the Networking section of VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
===Ports on your WeBWorK guest===<br />
Run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you see something like<br />
<br />
systemd-r 697 systemd-resolve 13u IPv4 19596 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
sshd 772 root 3u IPv4 21834 0t0 TCP *:22 (LISTEN)<br />
sshd 772 root 4u IPv6 21845 0t0 TCP *:22 (LISTEN)<br />
lighttpd 810 www-data 4u IPv4 22509 0t0 TCP *:8080 (LISTEN)<br />
mysqld 856 mysql 31u IPv6 23312 0t0 TCP *:33060 (LISTEN)<br />
mysqld 856 mysql 33u IPv4 23654 0t0 TCP 127.0.0.1:3306 (LISTEN)<br />
Rserve 865 rserveuser 3u IPv4 22878 0t0 TCP 127.0.0.1:6311 (LISTEN)<br />
/usr/sbin 946 root 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 956 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 957 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 958 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 959 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 960 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
<br />
===Ports on your Windows 11 Pro host===<br />
Open a Power Shell command window as an administrator and run the command (it can take awhile)<br />
PS C:\> netstat -ab<br />
<br />
Active Connections<br />
<br />
Proto Local Address Foreign Address State<br />
TCP 0.0.0.0:135 desktop:0 LISTENING<br />
RpcSs<br />
[svchost.exe]<br />
TCP 0.0.0.0:443 desktop:0 LISTENING<br />
[vmware-hostd.exe]<br />
TCP 0.0.0.0:445 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:903 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:913 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:2869 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:3306 desktop:0 LISTENING<br />
[mysqld.exe]<br />
...<br />
TCP 0.0.0.0:6000 desktop:0 LISTENING<br />
[XWin_MobaX.exe]<br />
TCP 0.0.0.0:49664 desktop:0 LISTENING<br />
...<br />
TCP 127.0.0.1:2222 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52916 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52917 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:4443 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
...<br />
<br />
===Ports on your Linux host===<br />
<br />
Run the command<br />
<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for ****: <br />
<br />
and you should see something like the following<br />
systemd-r 436 systemd-resolve 13u IPv4 18620 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
vmware-au 1284 root 10u IPv6 33012 0t0 TCP *:902 (LISTEN)<br />
vmware-au 1284 root 11u IPv4 33013 0t0 TCP *:902 (LISTEN)<br />
sshd 8786 root 3u IPv4 114131 0t0 TCP *:22 (LISTEN)<br />
sshd 8786 root 4u IPv6 114133 0t0 TCP *:22 (LISTEN)<br />
cupsd 12124 root 6u IPv6 138503 0t0 TCP [::1]:631 (LISTEN)<br />
cupsd 12124 root 7u IPv4 138504 0t0 TCP 127.0.0.1:631 (LISTEN)<br />
VirtualBo 17065 wwadmin 48u IPv4 185297 0t0 TCP 127.0.0.1:8081 (LISTEN)<br />
VirtualBo 17065 wwadmin 49u IPv4 185298 0t0 TCP 127.0.0.1:4443 (LISTEN)<br />
VirtualBo 17065 wwadmin 50u IPv4 185299 0t0 TCP 127.0.0.1:8080 (LISTEN)<br />
VirtualBo 17065 wwadmin 51u IPv4 185300 0t0 TCP 127.0.0.1:2222 (LISTEN)<br />
<br />
Notice that port forwarding for VirtualBox has been set up correctly.<br />
<br />
<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Virtual_Machine_Image&diff=24169WeBWorK 2.18 Ubuntu Server 22.04 LTS Virtual Machine Image2023-09-11T17:53:30Z<p>Apizer: /* VirtualBox 6 running on a Ubuntu 22.04 Desktop host */</p>
<hr />
<div><!--<br />
{{UnderConstruction}} <br />
--><br />
{{UnderConstruction}} <br />
These instructions cover the installation of the Ubuntu Server 22.04 LTS 64 bit operating system and WeBWorK 2.18 using the WeBWorK Virtual Machine Image. <br />
<br />
The WeBWorK Virtual Machine Image is an <code>.ova</code> file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, QEMU/KVM, etc. <br />
<br />
This image file has been tested on <br />
* VMware Workstation 17 Player<br />
* VirtualBox 7<br />
<br />
This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc.) installed and configured. <br />
<br />
== Installing from WW2.18 Ubuntu22.04 Server Virtual Machine Image ==<br />
<br />
===Overview===<br />
After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who has sudo privileges), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> who has professor privileges and also the Mjolicious secret (see below).<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]].<br />
<br />
===Download the ova image===<br />
<br />
Download the sha256 checksum and the .ova files from the WeBWorK Download Site below. <br />
<br />
You want to download the files <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code> and <code>WW2.18_Ubuntu22.04_Server.ova</code><br />
The ova is a 7.3 GB file.<br />
<br />
* [http://webwork.maa.org/ww-downloads/wwdownload.html WeBWorK Download Site]<br />
<br />
Verify the SHA256 checksum of your downloaded file <code>WW2.18_Ubuntu22.04_Server.ova</code> agrees with the one in <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code>.<br />
<br />
===OVA and OVF files===<br />
The <code>.ova</code> file is simply a tar bundle containing an <code>.ovf</code> file, one or more <code>.vmdk</code> files, a <code>.mf</code> file and possibly other files.<br />
* The <code>.ovf</code> file is an XML file which describes the packaged virtual machine and is human-readable. <br />
* The <code>.vmdk</code> file(s) contain the disk images(s).<br />
* Possibly other files<br />
* The <code>.mf</code> file contains SHA1 checksums for the above files.<br />
<br />
You can import a virtual machine either from an <code>.ova</code> file or from the <code>.ovf</code>, <code>.vmdk</code>, <code>.mf</code> collection. Sometimes importing from the <code>.ova</code> file may fail whereas importing from the <code>.ovf</code> or <code>.vmdk</code> file will succeed.<br />
<br />
You can extract the files in <code>WW2.18_Ubuntu22.04_Server.ova</code> with the command <br />
<br />
$ tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
<br />
You then can look at (and possibly edit) the human readable <code>WW2.18_Ubuntu22.04_Server.ofv</code> file. If you do edit the <code>WW2.18_Ubuntu22.04_Server.ofv</code> file, you will also have to compute the new SHA1 checksum and replace the old one in the <code>WW2.18_Ubuntu22.04_Server.mf</code> file for the files to be usable.<br />
<br />
===Installing the WeBWorK Virtual Machine Image ===<br />
<br />
Import the file <code>WW2.18_Ubuntu22.04_Server.ova</code> into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 17 Player <br />
running on a Windows 11 Pro host. It has been tested on <br />
* VMware Workstation 17 Player running on a Windows 11 host (Pro edition)<br />
* VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host<br />
* VirtualBox 7 running on a Windows 11 host (Home and Pro editions)<br />
* VirtualBox 6 running on a Ubuntu 22.04 Desktop host<br />
'''See [[#Specific Virtual Environments|Specific Virtual Environments]] below for installation information on specific virtual environments.'''<br />
<br />
====Processors, Memory, Hard Disk, Networking====<br />
The WeBWorK Virtual Machine Image was created with the following parameters:<br />
*20 GB dynamically allocated disk drive in VMDK format (single file) of which 13 GB is used<br />
*4 GB memory<br />
*2 cpu<br />
These resources are OK for testing and may suffice for a very small course but it is possible to overwhelm the machine. <br />
<br />
Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 17 Player running on a Windows 11 host). You should adjust these resources either when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk is more complicated. See [[#Specific Virtual Environments|Specific Virtual Environments]] below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see [[#Increase Disk Space|Increase Disk Space]] below). <br />
<br />
Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]) and/or look at [[#Debugging Networking Issues|Debugging Networking Issues]].<br />
<br />
===Import the .ova file===<br />
There may be specific information for your situation below. See<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
* [[#Amazon EC2|Amazon EC2]]<br />
<br />
===Your server===<br />
After importing, your virtual WeBWorK server will be identical to a system created by following the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] with the Webwork2 Mojolicious App being served directly via hypnotoad (option 1) and the Optional Configurations B and C implemented. '''Note that''' Option A (SSL) is not implemented (see [[#Set up WeBWorK to use SSL|Set up WeBWorK to use SSL]] below).<br />
<br />
'''Note''' that on some virtual environments, you may need to take additional actions. See the section [[#Specific Virtual Environments|Specific Virtual Environments]] below.<br />
<br />
You should read through the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] in order to understand how your server has been set up. Especially look at<br />
[[Installation Manual for 2.18 on Ubuntu#Notation|Notation in the Installation Manual for 2.18 on Ubuntu]] to understand the notation we use in these instructions.<br />
<br />
==Boot Your Server==<br />
===Log into your server ===<br />
After booting you should see a login prompt (you may have to press <code>&lt;Enter&gt;</code>).<br />
*Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges. We will denote<br />
wwadmin's password by <code><wwadmin password></code>. Initially this is set to <code>wwadmin</code>.<br />
If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.<br />
<br />
===Test your ip address===<br />
Run the command<br />
$ ip address show<br />
and look at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]). If that doesn't help look at [[#Debugging Networking Issues|Debugging Networking Issues]]. '''You have to fix this before you can go on to the next step'''.<br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program. <br />
<br />
You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with <code>copy</code> from the Edit menu or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit menu list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code> or <code>&lt;Shift&gt; &lt;Insert&gt;</code> depending on your application). <br />
<br />
My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. In any event, after testing, read the section [[#Make the WeBWorK Configuration Permanent|Make the WeBWorK Configuration Permanent]] below. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.<br />
<br />
I am assuming your network has been set up automatically.<br />
<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a <br />
terminal emulator running on your host using ssh, or from the terminal on the guest once you login. <br />
<br />
Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will probably see <br />
...<br />
Time zone: Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/New_York". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/New_York<br />
[sudo] password for wwadmin: <wwadmin password><br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
=== Checking for and Installing Hotfixes ===<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check_for_and_Install_Hotfixes in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
'''Important: The are bug fixes for both the webwork2 code and the pg code that occurred after the virtual machine image was built. You should definitely update both the webwork2 and pg code.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the virtual machine image was built. <br />
You should definitely update the webwork2 code.'''<br />
--><br />
<!--<br />
'''Important: The are bug fixes for the pg code that occurred after the virtual machine image was built. You should definitely update the pg code.'''<br />
--><br />
<br />
=== WeBWorK configuration ===<br />
<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
First we have to edit information about the network server setup. <br />
Search for <code>192.168.138.131</code> and replace that by your the new ip address you found above (<code>192.168.76.128</code> in our example above). <br />
<br />
'''But wait, this can be tricky'''. If you set up port forwarding (as we had to for VirtualBox), then instead use the code<br />
$server_root_url = 'http://localhost';<br />
<br />
The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM)<br />
<br />
$server_root_url = 'http://192.168.76.128';<br />
<br />
where of course your ip address may be different. The "http://" is important. <br />
<br />
'''Remark'''. First of all, let me admit I don't understand the above - it just works. If this is not set correctly (and I don't really understand what "correctly" means), then when you test the Library Browser, e.g. by clicking on <code>Library Browser</code> on the <code>Main Menu</code>, then on <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, you will not be able to select a <code>Chapter</code> and you will see an error message similar to<br />
183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.<br />
If you google this message, you will find a lot of people have seen this error and the most common reason is that <code>$server_root_url</code> has not been set correctly, whatever "correctly" means. A common error is to forget <code>http://</code> or to use <code>http://</code> when you should use <code>https://</code> (or vice versa) or to just have the wrong domain name or ip address.<br />
<br />
We now continue editing <code>site.conf</code> <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then.<br />
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.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.'''<br />
<br />
Then save the file and Quit. And restart the webwork2 app so that these changes take effect:<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
===Set up WeBWorK to use SSL===<br />
This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.<br />
<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Implement Option A (SSL)|Implement Option A (SSL) in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
Note that the Virtual Machine Image was built using Option 1: Serving Directly via Hypnotoad so that in the instructions for setting up SSL follow the section<br />
Set up Hypnotoad to use SSL (Option 1).<br />
<br />
===Finish up===<br />
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.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://192.168.76.128/webwork2</code> where of course you should use your actual ip address. If you have already set up https and haven't setup the redirect, then you should use <code>https://192.168.76.128/webwork2</code> . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.<br />
<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Make the WeBWorK Configuration Permanent==<br />
<br />
Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with <code>ip address show</code>) and used that when editing the <code>site.conf</code> file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.<br />
# The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the <code>site.conf</code> file. <br />
# The other method is to setup networking to use a fixed specific ip address for your server and use that in the <code>site.conf</code> file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the [[#Networking_2|Networking]] section under [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] below for information on editing these files. You can search the web for information on the correct syntax to use.<br />
<br />
Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections [[#Edit the site.conf file|Edit the site.conf file]] and [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]].<br />
<br />
Remember that any time you edit WeBWorK's configuration files, you have the restart the WeBWorK2 app for the changes to take effect; see [[Installation_Manual_for_2.18_on_Ubuntu#Enable_and_start_the_Webwork2_Systemd_Service|Enable_and_start_the_Webwork2_Systemd_Service in the Installation Manual for 2.18 on Ubuntu]]. For networking changes to take effect, you should reboot the server.<br />
<br />
==Passwords==<br />
It is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access.<br />
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. Also change the mojolicious.yml secret.<br />
====Change the mojolicious.yml secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
====Change the password for wwadmin====<br />
<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$ <br />
'''Do not forget the new <code>&lt;wwadmin password&gt;</code> that you just entered.''' Below when we refer to <wwadmin password>, we mean the '''new''' <wwadmin password>.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = "wwadmin";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. We refer to this password as <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart webwork2 so the changes take effect.<br />
<br />
$ sudo systemctl restart webwork2<br />
[sudo] password for wwadmin: <wwadmin password><br />
$<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,authentication_string,password,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <code>webworkWrite</code> should have <br />
a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT Host, User, password FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
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.<br />
<br />
====Change the password for profa====<br />
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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
http://192.168.76.128/webwork2/admin</code> <br />
http://192.168.76.128/webwork2/mytestcourse</code> <br />
where of course you should use your actual ip address.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust the mojolicious.yml configuration according to your server's memory===<br />
Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. <br />
Search for the lines<br />
clients: 1<br />
workers: 10<br />
spare: 5<br />
and edit the numbers depending on the amount of RAM available on your server. Look at the recommendations for these settings in the section immediately above these lines in the webwork2.mojolicious.yml file<br />
<br />
Then save the file and Quit.<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in [[#Specific Virtual Environments|Specific Virtual Environments]] below. <br />
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<br />
20 GB to 30GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 19G 11G 7.3G 59% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/sda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 21.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags: <br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 20.0GB 20.0GB ext4<br />
<br />
(parted)<br />
<br />
We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command<br />
(parted) resizepart<br />
Partition number? 2<br />
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [20GB]? 30GB<br />
(parted)<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 31.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags:<br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 30.0GB 30.0GB ext4<br />
<br />
(parted)<br />
Notice we now have a 30 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below<br />
$ sudo resize2fs /dev/sda2<br />
[sudo] password for wwadmin: <wwadmin password><br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/sda2 is mounted on /; on-line resizing required<br />
old_desc_blocks = 2, new_desc_blocks = 3<br />
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 29G 11G 18G 38% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
*'''Option A''' is not implemented. '''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
==Specific Virtual Environments==<br />
Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of<br />
the specific environments we have information on:<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 15 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
<br />
===VMware Workstation 17 Player running on a Windows 11 host===<br />
====Importing the ova File====<br />
For VMware Player select Player, File, Open and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file.<br />
Name your machine and select a storage path and then hit Import<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
====Accessing your server from your host====<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the '''WeBWorK Placeholder Page'''. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the '''WeBWorK''' Welcome page. <br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 17 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Windows 11 host===<br />
<br />
====Importing the ova File====<br />
For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file. Click Finish. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Initially networking will be broken. Do the following from your guest WeBWorK system<br />
$ sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
...<br />
logical name: enp0s17<br />
version: 02<br />
serial: 08:00:27:30:28:b6<br />
...<br />
Remember the logical name from your system as we will need it below. We have to backup and then edit one file.<br />
<br />
$ cd /etc/netplan/<br />
$ sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak1<br />
[sudo] password for wwadmin: <wwadmin password> <br />
Now edit the <code> 00-installer-config.yaml</code> file<br />
$ sudo nano 00-installer-config.yaml<br />
It should look like (I had to stretch the window to see the whole file):<br />
# This is the network config written by 'subiquity'<br />
network:<br />
ethernets:<br />
ens33:<br />
dhcp4: true<br />
version: 2<br />
Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.<br />
<br />
<br />
Now reboot your server,e.g.<br />
$ sudo reboot<br />
[sudo] password for wwadmin: <wwadmin password> <br />
login and run the command<br />
$ ip address show<br />
and look at the output, something like<br />
... <br />
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000<br />
link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff<br />
inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17<br />
...<br />
<br />
We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below. <br />
<br />
In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network"<br />
Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:<br />
<br />
{| class="wikitable"<br />
|+Port Forwarding<br />
!Name<br />
!Protocol<br />
!Host IP<br />
!Host Port<br />
!Guest IP<br />
!Guest Port<br />
|-<br />
|ssh<br />
|TCP<br />
|127.0.0.1<br />
|2222<br />
|10.0.2.15<br />
|22<br />
|-<br />
|https<br />
|TCP<br />
|127.0.0.1<br />
|4443<br />
|10.0.2.15<br />
|443<br />
|-<br />
|http<br />
|TCP<br />
|127.0.0.1<br />
|8081<br />
|10.0.2.15<br />
|80<br />
|}<br />
Double check that you have entered everything correctly ('''using''' your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".<br />
<br />
Now boot your server.<br />
<br />
====Accessing your server from your host====<br />
We need to employ the port forwarding rules above.<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up with the port forwarding rules above, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and you should the '''WeBWorK''' Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.<br />
<br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your guest is shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list <br />
(probably "WW2.18_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. <br />
Click “Apply” when you're done.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host===<br />
<br />
====Importing the ova File====<br />
For VMware Player select File, Open a Virtual Machine and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and import the file.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
Accessing your server is exactly the same as in [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]] above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.76.128<br />
where of course you need to use the ip address of your WeBWorK guest server.<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Ubuntu 22.04 Desktop host===<br />
====Importing the ova File====<br />
Importing the ova File is exactly the same as in [[#VirtualBox 76 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card)<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
# Set up port forwarding<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details.<br />
<br />
'''Except''' that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh -p 2222 wwadmin@127.0.0.1<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
The procedure is the same as in [[#Expand the disk drive_2|Expand the disk drive]] the Windows 11 case above.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===QEMU/KVM running on a Ubuntu 22.04 Desktop host===<br />
====First install Qemu-KVM====<br />
<br />
It is probably a good idea to first update and upgrade the system packages:<br />
$ sudo apt update<br />
$ sudo apt upgrade<br />
<br />
Now install Qemu-KVM<br />
$ sudo apt install -y qemu-kvm virt-manager libvirt-daemon-system virtinst libvirt-clients bridge-utils<br />
<br />
Enable and start libvirtd<br />
$ sudo systemctl enable --now libvirtd<br />
$ sudo systemctl start libvirtd<br />
and check that all is OK<br />
$ sudo systemctl status libvirtd<br />
<br />
Now add wwadmin to the kvm and libvirt groups.<br />
$ sudo usermod -aG kvm $USER<br />
$ sudo usermod -aG libvirt $USER<br />
<br />
====Convert the image to qcow2 format====<br />
<br />
cd to whatever directory you downloaded the <code>WW2.18_Ubuntu22.04_Server.ova</code> file to (maybe "Downloads") and then untar it<br />
tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
which might take awhile. Then run the command to covert the vmdk format to qcow2 format<br />
qemu-img convert -p -f vmdk -O qcow2 WW2.18_Ubuntu22.04_Server-disk1.vmdk WW2.18_Ubuntu22.04_Server.qcow2<br />
and move the qcow2 image to the correct location<br />
sudo mv WW2.18_Ubuntu22.04_Server.qcow2 /var/lib/libvirt/images/<br />
<br />
====Boot up your virtual machine====<br />
Start up Virtual Machine Manager (search for VM in the app manager). Note that if you run into problems running the Virtual Machine Manager (e.g. QEMU/KVM not connected), the first thing to try is rebooting your host machine.<br />
<br />
In the Virtual Machine Manager,<br />
select File, New Virtual Machine, Import existing disk image, Forward, Browse and finally select WW2.18_Ubuntu22.04_Server.qcow2. The select Choose Volume and enter Ubuntu 22.04 LTS for the operating system you are installing. Next click Forward and choose your memory and CPUs. Select Forward again, name your system and finally select finish.<br />
<br />
Now log into your virtual machine (wwadmin with password wwadmin)<br />
<br />
====Networking====<br />
<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card), probably something like enp1s0<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details '''except that'''<br />
# You do not need port forwarding<br />
# Instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.122.233<br />
(where of course you need to use the actual ip address of your guest WeBWorK server).<br />
<br />
====Expand the disk drive====<br />
You can do most of this from the graphical Virtual Machine Manager (select the machine, then Edit, Virtual Machine Details). Below are commands to this from the command line. I think you have to actually expand the disk from the command line but you can get information and add cpu's and/or memory from the graphical Virtual Machine Manager.<br />
<br />
I'm assume the name of your WeBWorK guest is <code>wwserver</code> and it is Shutoff. First find the location of the disk.<br />
Run the command<br />
$ sudo virsh domblklist wwserver<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
Target Source<br />
-------------------------------------------------------------------------<br />
sda /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
<br />
Now get some info about the disk<br />
$ sudo qemu-img info /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
image: /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
file format: qcow2<br />
virtual size: 12 GiB (12884901888 bytes)<br />
disk size: 6.76 GiB<br />
cluster_size: 65536<br />
Format specific information:<br />
compat: 1.1<br />
lazy refcounts: false<br />
refcount bits: 16<br />
corrupt: false<br />
<br />
and now lets resize it to 20 GB by adding 8 GB<br />
sudo qemu-img resize /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2 +8G<br />
[sudo] password for wwadmin: <wwadmin password><br />
Image resized.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===Amazon EC2===<br />
While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the [[WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image]] is faster and easier anyway.<br />
<br />
==Debugging Networking Issues==<br />
If after reading the information above on networking you are still having problems, maybe the information below will be of help.<br />
<br />
===One method===<br />
There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms:<br />
$ ip address show<br />
does not return an ip address and the WW guest can not access the outside world.<br />
<br />
In VirtualBox I built another guest from the <code>ubuntu-22.04-live-server-amd64.iso</code> using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by<br />
sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files<br />
/etc/netplan/00-installer-config.yaml<br />
and<br />
/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg<br />
BUT in the WW guest the information did not agree. This led to the information given in [[#Networking_2|the Networking section of VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
===Ports on your WeBWorK guest===<br />
Run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you see something like<br />
<br />
systemd-r 697 systemd-resolve 13u IPv4 19596 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
sshd 772 root 3u IPv4 21834 0t0 TCP *:22 (LISTEN)<br />
sshd 772 root 4u IPv6 21845 0t0 TCP *:22 (LISTEN)<br />
lighttpd 810 www-data 4u IPv4 22509 0t0 TCP *:8080 (LISTEN)<br />
mysqld 856 mysql 31u IPv6 23312 0t0 TCP *:33060 (LISTEN)<br />
mysqld 856 mysql 33u IPv4 23654 0t0 TCP 127.0.0.1:3306 (LISTEN)<br />
Rserve 865 rserveuser 3u IPv4 22878 0t0 TCP 127.0.0.1:6311 (LISTEN)<br />
/usr/sbin 946 root 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 956 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 957 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 958 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 959 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 960 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
<br />
===Ports on your Windows 11 Pro host===<br />
Open a Power Shell command window as an administrator and run the command (it can take awhile)<br />
PS C:\> netstat -ab<br />
<br />
Active Connections<br />
<br />
Proto Local Address Foreign Address State<br />
TCP 0.0.0.0:135 desktop:0 LISTENING<br />
RpcSs<br />
[svchost.exe]<br />
TCP 0.0.0.0:443 desktop:0 LISTENING<br />
[vmware-hostd.exe]<br />
TCP 0.0.0.0:445 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:903 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:913 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:2869 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:3306 desktop:0 LISTENING<br />
[mysqld.exe]<br />
...<br />
TCP 0.0.0.0:6000 desktop:0 LISTENING<br />
[XWin_MobaX.exe]<br />
TCP 0.0.0.0:49664 desktop:0 LISTENING<br />
...<br />
TCP 127.0.0.1:2222 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52916 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52917 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:4443 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
...<br />
<br />
===Ports on your Linux host===<br />
<br />
Run the command<br />
<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for ****: <br />
<br />
and you should see something like the following<br />
systemd-r 436 systemd-resolve 13u IPv4 18620 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
vmware-au 1284 root 10u IPv6 33012 0t0 TCP *:902 (LISTEN)<br />
vmware-au 1284 root 11u IPv4 33013 0t0 TCP *:902 (LISTEN)<br />
sshd 8786 root 3u IPv4 114131 0t0 TCP *:22 (LISTEN)<br />
sshd 8786 root 4u IPv6 114133 0t0 TCP *:22 (LISTEN)<br />
cupsd 12124 root 6u IPv6 138503 0t0 TCP [::1]:631 (LISTEN)<br />
cupsd 12124 root 7u IPv4 138504 0t0 TCP 127.0.0.1:631 (LISTEN)<br />
VirtualBo 17065 wwadmin 48u IPv4 185297 0t0 TCP 127.0.0.1:8081 (LISTEN)<br />
VirtualBo 17065 wwadmin 49u IPv4 185298 0t0 TCP 127.0.0.1:4443 (LISTEN)<br />
VirtualBo 17065 wwadmin 50u IPv4 185299 0t0 TCP 127.0.0.1:8080 (LISTEN)<br />
VirtualBo 17065 wwadmin 51u IPv4 185300 0t0 TCP 127.0.0.1:2222 (LISTEN)<br />
<br />
Notice that port forwarding for VirtualBox has been set up correctly.<br />
<br />
<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Virtual_Machine_Image&diff=24168WeBWorK 2.18 Ubuntu Server 22.04 LTS Virtual Machine Image2023-09-11T17:51:01Z<p>Apizer: /* Networking */</p>
<hr />
<div><!--<br />
{{UnderConstruction}} <br />
--><br />
{{UnderConstruction}} <br />
These instructions cover the installation of the Ubuntu Server 22.04 LTS 64 bit operating system and WeBWorK 2.18 using the WeBWorK Virtual Machine Image. <br />
<br />
The WeBWorK Virtual Machine Image is an <code>.ova</code> file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, QEMU/KVM, etc. <br />
<br />
This image file has been tested on <br />
* VMware Workstation 17 Player<br />
* VirtualBox 7<br />
<br />
This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc.) installed and configured. <br />
<br />
== Installing from WW2.18 Ubuntu22.04 Server Virtual Machine Image ==<br />
<br />
===Overview===<br />
After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who has sudo privileges), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> who has professor privileges and also the Mjolicious secret (see below).<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]].<br />
<br />
===Download the ova image===<br />
<br />
Download the sha256 checksum and the .ova files from the WeBWorK Download Site below. <br />
<br />
You want to download the files <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code> and <code>WW2.18_Ubuntu22.04_Server.ova</code><br />
The ova is a 7.3 GB file.<br />
<br />
* [http://webwork.maa.org/ww-downloads/wwdownload.html WeBWorK Download Site]<br />
<br />
Verify the SHA256 checksum of your downloaded file <code>WW2.18_Ubuntu22.04_Server.ova</code> agrees with the one in <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code>.<br />
<br />
===OVA and OVF files===<br />
The <code>.ova</code> file is simply a tar bundle containing an <code>.ovf</code> file, one or more <code>.vmdk</code> files, a <code>.mf</code> file and possibly other files.<br />
* The <code>.ovf</code> file is an XML file which describes the packaged virtual machine and is human-readable. <br />
* The <code>.vmdk</code> file(s) contain the disk images(s).<br />
* Possibly other files<br />
* The <code>.mf</code> file contains SHA1 checksums for the above files.<br />
<br />
You can import a virtual machine either from an <code>.ova</code> file or from the <code>.ovf</code>, <code>.vmdk</code>, <code>.mf</code> collection. Sometimes importing from the <code>.ova</code> file may fail whereas importing from the <code>.ovf</code> or <code>.vmdk</code> file will succeed.<br />
<br />
You can extract the files in <code>WW2.18_Ubuntu22.04_Server.ova</code> with the command <br />
<br />
$ tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
<br />
You then can look at (and possibly edit) the human readable <code>WW2.18_Ubuntu22.04_Server.ofv</code> file. If you do edit the <code>WW2.18_Ubuntu22.04_Server.ofv</code> file, you will also have to compute the new SHA1 checksum and replace the old one in the <code>WW2.18_Ubuntu22.04_Server.mf</code> file for the files to be usable.<br />
<br />
===Installing the WeBWorK Virtual Machine Image ===<br />
<br />
Import the file <code>WW2.18_Ubuntu22.04_Server.ova</code> into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 17 Player <br />
running on a Windows 11 Pro host. It has been tested on <br />
* VMware Workstation 17 Player running on a Windows 11 host (Pro edition)<br />
* VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host<br />
* VirtualBox 7 running on a Windows 11 host (Home and Pro editions)<br />
* VirtualBox 6 running on a Ubuntu 22.04 Desktop host<br />
'''See [[#Specific Virtual Environments|Specific Virtual Environments]] below for installation information on specific virtual environments.'''<br />
<br />
====Processors, Memory, Hard Disk, Networking====<br />
The WeBWorK Virtual Machine Image was created with the following parameters:<br />
*20 GB dynamically allocated disk drive in VMDK format (single file) of which 13 GB is used<br />
*4 GB memory<br />
*2 cpu<br />
These resources are OK for testing and may suffice for a very small course but it is possible to overwhelm the machine. <br />
<br />
Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 17 Player running on a Windows 11 host). You should adjust these resources either when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk is more complicated. See [[#Specific Virtual Environments|Specific Virtual Environments]] below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see [[#Increase Disk Space|Increase Disk Space]] below). <br />
<br />
Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]) and/or look at [[#Debugging Networking Issues|Debugging Networking Issues]].<br />
<br />
===Import the .ova file===<br />
There may be specific information for your situation below. See<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
* [[#Amazon EC2|Amazon EC2]]<br />
<br />
===Your server===<br />
After importing, your virtual WeBWorK server will be identical to a system created by following the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] with the Webwork2 Mojolicious App being served directly via hypnotoad (option 1) and the Optional Configurations B and C implemented. '''Note that''' Option A (SSL) is not implemented (see [[#Set up WeBWorK to use SSL|Set up WeBWorK to use SSL]] below).<br />
<br />
'''Note''' that on some virtual environments, you may need to take additional actions. See the section [[#Specific Virtual Environments|Specific Virtual Environments]] below.<br />
<br />
You should read through the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] in order to understand how your server has been set up. Especially look at<br />
[[Installation Manual for 2.18 on Ubuntu#Notation|Notation in the Installation Manual for 2.18 on Ubuntu]] to understand the notation we use in these instructions.<br />
<br />
==Boot Your Server==<br />
===Log into your server ===<br />
After booting you should see a login prompt (you may have to press <code>&lt;Enter&gt;</code>).<br />
*Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges. We will denote<br />
wwadmin's password by <code><wwadmin password></code>. Initially this is set to <code>wwadmin</code>.<br />
If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.<br />
<br />
===Test your ip address===<br />
Run the command<br />
$ ip address show<br />
and look at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]). If that doesn't help look at [[#Debugging Networking Issues|Debugging Networking Issues]]. '''You have to fix this before you can go on to the next step'''.<br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program. <br />
<br />
You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with <code>copy</code> from the Edit menu or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit menu list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code> or <code>&lt;Shift&gt; &lt;Insert&gt;</code> depending on your application). <br />
<br />
My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. In any event, after testing, read the section [[#Make the WeBWorK Configuration Permanent|Make the WeBWorK Configuration Permanent]] below. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.<br />
<br />
I am assuming your network has been set up automatically.<br />
<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a <br />
terminal emulator running on your host using ssh, or from the terminal on the guest once you login. <br />
<br />
Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will probably see <br />
...<br />
Time zone: Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/New_York". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/New_York<br />
[sudo] password for wwadmin: <wwadmin password><br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
=== Checking for and Installing Hotfixes ===<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check_for_and_Install_Hotfixes in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
'''Important: The are bug fixes for both the webwork2 code and the pg code that occurred after the virtual machine image was built. You should definitely update both the webwork2 and pg code.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the virtual machine image was built. <br />
You should definitely update the webwork2 code.'''<br />
--><br />
<!--<br />
'''Important: The are bug fixes for the pg code that occurred after the virtual machine image was built. You should definitely update the pg code.'''<br />
--><br />
<br />
=== WeBWorK configuration ===<br />
<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
First we have to edit information about the network server setup. <br />
Search for <code>192.168.138.131</code> and replace that by your the new ip address you found above (<code>192.168.76.128</code> in our example above). <br />
<br />
'''But wait, this can be tricky'''. If you set up port forwarding (as we had to for VirtualBox), then instead use the code<br />
$server_root_url = 'http://localhost';<br />
<br />
The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM)<br />
<br />
$server_root_url = 'http://192.168.76.128';<br />
<br />
where of course your ip address may be different. The "http://" is important. <br />
<br />
'''Remark'''. First of all, let me admit I don't understand the above - it just works. If this is not set correctly (and I don't really understand what "correctly" means), then when you test the Library Browser, e.g. by clicking on <code>Library Browser</code> on the <code>Main Menu</code>, then on <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, you will not be able to select a <code>Chapter</code> and you will see an error message similar to<br />
183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.<br />
If you google this message, you will find a lot of people have seen this error and the most common reason is that <code>$server_root_url</code> has not been set correctly, whatever "correctly" means. A common error is to forget <code>http://</code> or to use <code>http://</code> when you should use <code>https://</code> (or vice versa) or to just have the wrong domain name or ip address.<br />
<br />
We now continue editing <code>site.conf</code> <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then.<br />
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.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.'''<br />
<br />
Then save the file and Quit. And restart the webwork2 app so that these changes take effect:<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
===Set up WeBWorK to use SSL===<br />
This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.<br />
<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Implement Option A (SSL)|Implement Option A (SSL) in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
Note that the Virtual Machine Image was built using Option 1: Serving Directly via Hypnotoad so that in the instructions for setting up SSL follow the section<br />
Set up Hypnotoad to use SSL (Option 1).<br />
<br />
===Finish up===<br />
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.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://192.168.76.128/webwork2</code> where of course you should use your actual ip address. If you have already set up https and haven't setup the redirect, then you should use <code>https://192.168.76.128/webwork2</code> . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.<br />
<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Make the WeBWorK Configuration Permanent==<br />
<br />
Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with <code>ip address show</code>) and used that when editing the <code>site.conf</code> file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.<br />
# The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the <code>site.conf</code> file. <br />
# The other method is to setup networking to use a fixed specific ip address for your server and use that in the <code>site.conf</code> file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the [[#Networking_2|Networking]] section under [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] below for information on editing these files. You can search the web for information on the correct syntax to use.<br />
<br />
Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections [[#Edit the site.conf file|Edit the site.conf file]] and [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]].<br />
<br />
Remember that any time you edit WeBWorK's configuration files, you have the restart the WeBWorK2 app for the changes to take effect; see [[Installation_Manual_for_2.18_on_Ubuntu#Enable_and_start_the_Webwork2_Systemd_Service|Enable_and_start_the_Webwork2_Systemd_Service in the Installation Manual for 2.18 on Ubuntu]]. For networking changes to take effect, you should reboot the server.<br />
<br />
==Passwords==<br />
It is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access.<br />
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. Also change the mojolicious.yml secret.<br />
====Change the mojolicious.yml secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
====Change the password for wwadmin====<br />
<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$ <br />
'''Do not forget the new <code>&lt;wwadmin password&gt;</code> that you just entered.''' Below when we refer to <wwadmin password>, we mean the '''new''' <wwadmin password>.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = "wwadmin";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. We refer to this password as <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart webwork2 so the changes take effect.<br />
<br />
$ sudo systemctl restart webwork2<br />
[sudo] password for wwadmin: <wwadmin password><br />
$<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,authentication_string,password,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <code>webworkWrite</code> should have <br />
a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT Host, User, password FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
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.<br />
<br />
====Change the password for profa====<br />
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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
http://192.168.76.128/webwork2/admin</code> <br />
http://192.168.76.128/webwork2/mytestcourse</code> <br />
where of course you should use your actual ip address.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust the mojolicious.yml configuration according to your server's memory===<br />
Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. <br />
Search for the lines<br />
clients: 1<br />
workers: 10<br />
spare: 5<br />
and edit the numbers depending on the amount of RAM available on your server. Look at the recommendations for these settings in the section immediately above these lines in the webwork2.mojolicious.yml file<br />
<br />
Then save the file and Quit.<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in [[#Specific Virtual Environments|Specific Virtual Environments]] below. <br />
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<br />
20 GB to 30GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 19G 11G 7.3G 59% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/sda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 21.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags: <br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 20.0GB 20.0GB ext4<br />
<br />
(parted)<br />
<br />
We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command<br />
(parted) resizepart<br />
Partition number? 2<br />
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [20GB]? 30GB<br />
(parted)<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 31.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags:<br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 30.0GB 30.0GB ext4<br />
<br />
(parted)<br />
Notice we now have a 30 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below<br />
$ sudo resize2fs /dev/sda2<br />
[sudo] password for wwadmin: <wwadmin password><br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/sda2 is mounted on /; on-line resizing required<br />
old_desc_blocks = 2, new_desc_blocks = 3<br />
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 29G 11G 18G 38% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
*'''Option A''' is not implemented. '''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
==Specific Virtual Environments==<br />
Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of<br />
the specific environments we have information on:<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 15 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
<br />
===VMware Workstation 17 Player running on a Windows 11 host===<br />
====Importing the ova File====<br />
For VMware Player select Player, File, Open and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file.<br />
Name your machine and select a storage path and then hit Import<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
====Accessing your server from your host====<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the '''WeBWorK Placeholder Page'''. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the '''WeBWorK''' Welcome page. <br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 17 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Windows 11 host===<br />
<br />
====Importing the ova File====<br />
For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file. Click Finish. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Initially networking will be broken. Do the following from your guest WeBWorK system<br />
$ sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
...<br />
logical name: enp0s17<br />
version: 02<br />
serial: 08:00:27:30:28:b6<br />
...<br />
Remember the logical name from your system as we will need it below. We have to backup and then edit one file.<br />
<br />
$ cd /etc/netplan/<br />
$ sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak1<br />
[sudo] password for wwadmin: <wwadmin password> <br />
Now edit the <code> 00-installer-config.yaml</code> file<br />
$ sudo nano 00-installer-config.yaml<br />
It should look like (I had to stretch the window to see the whole file):<br />
# This is the network config written by 'subiquity'<br />
network:<br />
ethernets:<br />
ens33:<br />
dhcp4: true<br />
version: 2<br />
Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.<br />
<br />
<br />
Now reboot your server,e.g.<br />
$ sudo reboot<br />
[sudo] password for wwadmin: <wwadmin password> <br />
login and run the command<br />
$ ip address show<br />
and look at the output, something like<br />
... <br />
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000<br />
link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff<br />
inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17<br />
...<br />
<br />
We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below. <br />
<br />
In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network"<br />
Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:<br />
<br />
{| class="wikitable"<br />
|+Port Forwarding<br />
!Name<br />
!Protocol<br />
!Host IP<br />
!Host Port<br />
!Guest IP<br />
!Guest Port<br />
|-<br />
|ssh<br />
|TCP<br />
|127.0.0.1<br />
|2222<br />
|10.0.2.15<br />
|22<br />
|-<br />
|https<br />
|TCP<br />
|127.0.0.1<br />
|4443<br />
|10.0.2.15<br />
|443<br />
|-<br />
|http<br />
|TCP<br />
|127.0.0.1<br />
|8081<br />
|10.0.2.15<br />
|80<br />
|}<br />
Double check that you have entered everything correctly ('''using''' your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".<br />
<br />
Now boot your server.<br />
<br />
====Accessing your server from your host====<br />
We need to employ the port forwarding rules above.<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up with the port forwarding rules above, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and you should the '''WeBWorK''' Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.<br />
<br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your guest is shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list <br />
(probably "WW2.18_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. <br />
Click “Apply” when you're done.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host===<br />
<br />
====Importing the ova File====<br />
For VMware Player select File, Open a Virtual Machine and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and import the file.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
Accessing your server is exactly the same as in [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]] above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.76.128<br />
where of course you need to use the ip address of your WeBWorK guest server.<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 6 running on a Ubuntu 22.04 Desktop host===<br />
====Importing the ova File====<br />
Importing the ova File is exactly the same as in [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Accessing your server involves the same procedure as in [[#VirtualBox 6 running on a Windows 101 host|VirtualBox 6 running on a Windows 11 host]] above. So you have to<br />
# Find the name and MAC address of the virtual nic (network interface card)<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
# Set up port forwarding<br />
See [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above for details.<br />
<br />
'''Except''' that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh -p 2222 wwadmin@127.0.0.1<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
The procedure is the same as in [[#Expand the disk drive_2|Expand the disk drive]] the Windows 11 case above.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===QEMU/KVM running on a Ubuntu 22.04 Desktop host===<br />
====First install Qemu-KVM====<br />
<br />
It is probably a good idea to first update and upgrade the system packages:<br />
$ sudo apt update<br />
$ sudo apt upgrade<br />
<br />
Now install Qemu-KVM<br />
$ sudo apt install -y qemu-kvm virt-manager libvirt-daemon-system virtinst libvirt-clients bridge-utils<br />
<br />
Enable and start libvirtd<br />
$ sudo systemctl enable --now libvirtd<br />
$ sudo systemctl start libvirtd<br />
and check that all is OK<br />
$ sudo systemctl status libvirtd<br />
<br />
Now add wwadmin to the kvm and libvirt groups.<br />
$ sudo usermod -aG kvm $USER<br />
$ sudo usermod -aG libvirt $USER<br />
<br />
====Convert the image to qcow2 format====<br />
<br />
cd to whatever directory you downloaded the <code>WW2.18_Ubuntu22.04_Server.ova</code> file to (maybe "Downloads") and then untar it<br />
tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
which might take awhile. Then run the command to covert the vmdk format to qcow2 format<br />
qemu-img convert -p -f vmdk -O qcow2 WW2.18_Ubuntu22.04_Server-disk1.vmdk WW2.18_Ubuntu22.04_Server.qcow2<br />
and move the qcow2 image to the correct location<br />
sudo mv WW2.18_Ubuntu22.04_Server.qcow2 /var/lib/libvirt/images/<br />
<br />
====Boot up your virtual machine====<br />
Start up Virtual Machine Manager (search for VM in the app manager). Note that if you run into problems running the Virtual Machine Manager (e.g. QEMU/KVM not connected), the first thing to try is rebooting your host machine.<br />
<br />
In the Virtual Machine Manager,<br />
select File, New Virtual Machine, Import existing disk image, Forward, Browse and finally select WW2.18_Ubuntu22.04_Server.qcow2. The select Choose Volume and enter Ubuntu 22.04 LTS for the operating system you are installing. Next click Forward and choose your memory and CPUs. Select Forward again, name your system and finally select finish.<br />
<br />
Now log into your virtual machine (wwadmin with password wwadmin)<br />
<br />
====Networking====<br />
<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card), probably something like enp1s0<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details '''except that'''<br />
# You do not need port forwarding<br />
# Instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.122.233<br />
(where of course you need to use the actual ip address of your guest WeBWorK server).<br />
<br />
====Expand the disk drive====<br />
You can do most of this from the graphical Virtual Machine Manager (select the machine, then Edit, Virtual Machine Details). Below are commands to this from the command line. I think you have to actually expand the disk from the command line but you can get information and add cpu's and/or memory from the graphical Virtual Machine Manager.<br />
<br />
I'm assume the name of your WeBWorK guest is <code>wwserver</code> and it is Shutoff. First find the location of the disk.<br />
Run the command<br />
$ sudo virsh domblklist wwserver<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
Target Source<br />
-------------------------------------------------------------------------<br />
sda /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
<br />
Now get some info about the disk<br />
$ sudo qemu-img info /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
image: /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
file format: qcow2<br />
virtual size: 12 GiB (12884901888 bytes)<br />
disk size: 6.76 GiB<br />
cluster_size: 65536<br />
Format specific information:<br />
compat: 1.1<br />
lazy refcounts: false<br />
refcount bits: 16<br />
corrupt: false<br />
<br />
and now lets resize it to 20 GB by adding 8 GB<br />
sudo qemu-img resize /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2 +8G<br />
[sudo] password for wwadmin: <wwadmin password><br />
Image resized.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===Amazon EC2===<br />
While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the [[WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image]] is faster and easier anyway.<br />
<br />
==Debugging Networking Issues==<br />
If after reading the information above on networking you are still having problems, maybe the information below will be of help.<br />
<br />
===One method===<br />
There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms:<br />
$ ip address show<br />
does not return an ip address and the WW guest can not access the outside world.<br />
<br />
In VirtualBox I built another guest from the <code>ubuntu-22.04-live-server-amd64.iso</code> using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by<br />
sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files<br />
/etc/netplan/00-installer-config.yaml<br />
and<br />
/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg<br />
BUT in the WW guest the information did not agree. This led to the information given in [[#Networking_2|the Networking section of VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
===Ports on your WeBWorK guest===<br />
Run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you see something like<br />
<br />
systemd-r 697 systemd-resolve 13u IPv4 19596 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
sshd 772 root 3u IPv4 21834 0t0 TCP *:22 (LISTEN)<br />
sshd 772 root 4u IPv6 21845 0t0 TCP *:22 (LISTEN)<br />
lighttpd 810 www-data 4u IPv4 22509 0t0 TCP *:8080 (LISTEN)<br />
mysqld 856 mysql 31u IPv6 23312 0t0 TCP *:33060 (LISTEN)<br />
mysqld 856 mysql 33u IPv4 23654 0t0 TCP 127.0.0.1:3306 (LISTEN)<br />
Rserve 865 rserveuser 3u IPv4 22878 0t0 TCP 127.0.0.1:6311 (LISTEN)<br />
/usr/sbin 946 root 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 956 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 957 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 958 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 959 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 960 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
<br />
===Ports on your Windows 11 Pro host===<br />
Open a Power Shell command window as an administrator and run the command (it can take awhile)<br />
PS C:\> netstat -ab<br />
<br />
Active Connections<br />
<br />
Proto Local Address Foreign Address State<br />
TCP 0.0.0.0:135 desktop:0 LISTENING<br />
RpcSs<br />
[svchost.exe]<br />
TCP 0.0.0.0:443 desktop:0 LISTENING<br />
[vmware-hostd.exe]<br />
TCP 0.0.0.0:445 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:903 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:913 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:2869 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:3306 desktop:0 LISTENING<br />
[mysqld.exe]<br />
...<br />
TCP 0.0.0.0:6000 desktop:0 LISTENING<br />
[XWin_MobaX.exe]<br />
TCP 0.0.0.0:49664 desktop:0 LISTENING<br />
...<br />
TCP 127.0.0.1:2222 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52916 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52917 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:4443 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
...<br />
<br />
===Ports on your Linux host===<br />
<br />
Run the command<br />
<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for ****: <br />
<br />
and you should see something like the following<br />
systemd-r 436 systemd-resolve 13u IPv4 18620 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
vmware-au 1284 root 10u IPv6 33012 0t0 TCP *:902 (LISTEN)<br />
vmware-au 1284 root 11u IPv4 33013 0t0 TCP *:902 (LISTEN)<br />
sshd 8786 root 3u IPv4 114131 0t0 TCP *:22 (LISTEN)<br />
sshd 8786 root 4u IPv6 114133 0t0 TCP *:22 (LISTEN)<br />
cupsd 12124 root 6u IPv6 138503 0t0 TCP [::1]:631 (LISTEN)<br />
cupsd 12124 root 7u IPv4 138504 0t0 TCP 127.0.0.1:631 (LISTEN)<br />
VirtualBo 17065 wwadmin 48u IPv4 185297 0t0 TCP 127.0.0.1:8081 (LISTEN)<br />
VirtualBo 17065 wwadmin 49u IPv4 185298 0t0 TCP 127.0.0.1:4443 (LISTEN)<br />
VirtualBo 17065 wwadmin 50u IPv4 185299 0t0 TCP 127.0.0.1:8080 (LISTEN)<br />
VirtualBo 17065 wwadmin 51u IPv4 185300 0t0 TCP 127.0.0.1:2222 (LISTEN)<br />
<br />
Notice that port forwarding for VirtualBox has been set up correctly.<br />
<br />
<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Virtual_Machine_Image&diff=24167WeBWorK 2.18 Ubuntu Server 22.04 LTS Virtual Machine Image2023-09-11T17:49:24Z<p>Apizer: /* Networking */</p>
<hr />
<div><!--<br />
{{UnderConstruction}} <br />
--><br />
{{UnderConstruction}} <br />
These instructions cover the installation of the Ubuntu Server 22.04 LTS 64 bit operating system and WeBWorK 2.18 using the WeBWorK Virtual Machine Image. <br />
<br />
The WeBWorK Virtual Machine Image is an <code>.ova</code> file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, QEMU/KVM, etc. <br />
<br />
This image file has been tested on <br />
* VMware Workstation 17 Player<br />
* VirtualBox 7<br />
<br />
This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc.) installed and configured. <br />
<br />
== Installing from WW2.18 Ubuntu22.04 Server Virtual Machine Image ==<br />
<br />
===Overview===<br />
After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who has sudo privileges), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> who has professor privileges and also the Mjolicious secret (see below).<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]].<br />
<br />
===Download the ova image===<br />
<br />
Download the sha256 checksum and the .ova files from the WeBWorK Download Site below. <br />
<br />
You want to download the files <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code> and <code>WW2.18_Ubuntu22.04_Server.ova</code><br />
The ova is a 7.3 GB file.<br />
<br />
* [http://webwork.maa.org/ww-downloads/wwdownload.html WeBWorK Download Site]<br />
<br />
Verify the SHA256 checksum of your downloaded file <code>WW2.18_Ubuntu22.04_Server.ova</code> agrees with the one in <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code>.<br />
<br />
===OVA and OVF files===<br />
The <code>.ova</code> file is simply a tar bundle containing an <code>.ovf</code> file, one or more <code>.vmdk</code> files, a <code>.mf</code> file and possibly other files.<br />
* The <code>.ovf</code> file is an XML file which describes the packaged virtual machine and is human-readable. <br />
* The <code>.vmdk</code> file(s) contain the disk images(s).<br />
* Possibly other files<br />
* The <code>.mf</code> file contains SHA1 checksums for the above files.<br />
<br />
You can import a virtual machine either from an <code>.ova</code> file or from the <code>.ovf</code>, <code>.vmdk</code>, <code>.mf</code> collection. Sometimes importing from the <code>.ova</code> file may fail whereas importing from the <code>.ovf</code> or <code>.vmdk</code> file will succeed.<br />
<br />
You can extract the files in <code>WW2.18_Ubuntu22.04_Server.ova</code> with the command <br />
<br />
$ tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
<br />
You then can look at (and possibly edit) the human readable <code>WW2.18_Ubuntu22.04_Server.ofv</code> file. If you do edit the <code>WW2.18_Ubuntu22.04_Server.ofv</code> file, you will also have to compute the new SHA1 checksum and replace the old one in the <code>WW2.18_Ubuntu22.04_Server.mf</code> file for the files to be usable.<br />
<br />
===Installing the WeBWorK Virtual Machine Image ===<br />
<br />
Import the file <code>WW2.18_Ubuntu22.04_Server.ova</code> into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 17 Player <br />
running on a Windows 11 Pro host. It has been tested on <br />
* VMware Workstation 17 Player running on a Windows 11 host (Pro edition)<br />
* VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host<br />
* VirtualBox 7 running on a Windows 11 host (Home and Pro editions)<br />
* VirtualBox 6 running on a Ubuntu 22.04 Desktop host<br />
'''See [[#Specific Virtual Environments|Specific Virtual Environments]] below for installation information on specific virtual environments.'''<br />
<br />
====Processors, Memory, Hard Disk, Networking====<br />
The WeBWorK Virtual Machine Image was created with the following parameters:<br />
*20 GB dynamically allocated disk drive in VMDK format (single file) of which 13 GB is used<br />
*4 GB memory<br />
*2 cpu<br />
These resources are OK for testing and may suffice for a very small course but it is possible to overwhelm the machine. <br />
<br />
Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 17 Player running on a Windows 11 host). You should adjust these resources either when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk is more complicated. See [[#Specific Virtual Environments|Specific Virtual Environments]] below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see [[#Increase Disk Space|Increase Disk Space]] below). <br />
<br />
Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]) and/or look at [[#Debugging Networking Issues|Debugging Networking Issues]].<br />
<br />
===Import the .ova file===<br />
There may be specific information for your situation below. See<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
* [[#Amazon EC2|Amazon EC2]]<br />
<br />
===Your server===<br />
After importing, your virtual WeBWorK server will be identical to a system created by following the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] with the Webwork2 Mojolicious App being served directly via hypnotoad (option 1) and the Optional Configurations B and C implemented. '''Note that''' Option A (SSL) is not implemented (see [[#Set up WeBWorK to use SSL|Set up WeBWorK to use SSL]] below).<br />
<br />
'''Note''' that on some virtual environments, you may need to take additional actions. See the section [[#Specific Virtual Environments|Specific Virtual Environments]] below.<br />
<br />
You should read through the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] in order to understand how your server has been set up. Especially look at<br />
[[Installation Manual for 2.18 on Ubuntu#Notation|Notation in the Installation Manual for 2.18 on Ubuntu]] to understand the notation we use in these instructions.<br />
<br />
==Boot Your Server==<br />
===Log into your server ===<br />
After booting you should see a login prompt (you may have to press <code>&lt;Enter&gt;</code>).<br />
*Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges. We will denote<br />
wwadmin's password by <code><wwadmin password></code>. Initially this is set to <code>wwadmin</code>.<br />
If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.<br />
<br />
===Test your ip address===<br />
Run the command<br />
$ ip address show<br />
and look at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]). If that doesn't help look at [[#Debugging Networking Issues|Debugging Networking Issues]]. '''You have to fix this before you can go on to the next step'''.<br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program. <br />
<br />
You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with <code>copy</code> from the Edit menu or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit menu list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code> or <code>&lt;Shift&gt; &lt;Insert&gt;</code> depending on your application). <br />
<br />
My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. In any event, after testing, read the section [[#Make the WeBWorK Configuration Permanent|Make the WeBWorK Configuration Permanent]] below. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.<br />
<br />
I am assuming your network has been set up automatically.<br />
<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a <br />
terminal emulator running on your host using ssh, or from the terminal on the guest once you login. <br />
<br />
Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will probably see <br />
...<br />
Time zone: Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/New_York". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/New_York<br />
[sudo] password for wwadmin: <wwadmin password><br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
=== Checking for and Installing Hotfixes ===<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check_for_and_Install_Hotfixes in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
'''Important: The are bug fixes for both the webwork2 code and the pg code that occurred after the virtual machine image was built. You should definitely update both the webwork2 and pg code.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the virtual machine image was built. <br />
You should definitely update the webwork2 code.'''<br />
--><br />
<!--<br />
'''Important: The are bug fixes for the pg code that occurred after the virtual machine image was built. You should definitely update the pg code.'''<br />
--><br />
<br />
=== WeBWorK configuration ===<br />
<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
First we have to edit information about the network server setup. <br />
Search for <code>192.168.138.131</code> and replace that by your the new ip address you found above (<code>192.168.76.128</code> in our example above). <br />
<br />
'''But wait, this can be tricky'''. If you set up port forwarding (as we had to for VirtualBox), then instead use the code<br />
$server_root_url = 'http://localhost';<br />
<br />
The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM)<br />
<br />
$server_root_url = 'http://192.168.76.128';<br />
<br />
where of course your ip address may be different. The "http://" is important. <br />
<br />
'''Remark'''. First of all, let me admit I don't understand the above - it just works. If this is not set correctly (and I don't really understand what "correctly" means), then when you test the Library Browser, e.g. by clicking on <code>Library Browser</code> on the <code>Main Menu</code>, then on <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, you will not be able to select a <code>Chapter</code> and you will see an error message similar to<br />
183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.<br />
If you google this message, you will find a lot of people have seen this error and the most common reason is that <code>$server_root_url</code> has not been set correctly, whatever "correctly" means. A common error is to forget <code>http://</code> or to use <code>http://</code> when you should use <code>https://</code> (or vice versa) or to just have the wrong domain name or ip address.<br />
<br />
We now continue editing <code>site.conf</code> <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then.<br />
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.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.'''<br />
<br />
Then save the file and Quit. And restart the webwork2 app so that these changes take effect:<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
===Set up WeBWorK to use SSL===<br />
This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.<br />
<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Implement Option A (SSL)|Implement Option A (SSL) in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
Note that the Virtual Machine Image was built using Option 1: Serving Directly via Hypnotoad so that in the instructions for setting up SSL follow the section<br />
Set up Hypnotoad to use SSL (Option 1).<br />
<br />
===Finish up===<br />
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.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://192.168.76.128/webwork2</code> where of course you should use your actual ip address. If you have already set up https and haven't setup the redirect, then you should use <code>https://192.168.76.128/webwork2</code> . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.<br />
<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Make the WeBWorK Configuration Permanent==<br />
<br />
Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with <code>ip address show</code>) and used that when editing the <code>site.conf</code> file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.<br />
# The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the <code>site.conf</code> file. <br />
# The other method is to setup networking to use a fixed specific ip address for your server and use that in the <code>site.conf</code> file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the [[#Networking_2|Networking]] section under [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] below for information on editing these files. You can search the web for information on the correct syntax to use.<br />
<br />
Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections [[#Edit the site.conf file|Edit the site.conf file]] and [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]].<br />
<br />
Remember that any time you edit WeBWorK's configuration files, you have the restart the WeBWorK2 app for the changes to take effect; see [[Installation_Manual_for_2.18_on_Ubuntu#Enable_and_start_the_Webwork2_Systemd_Service|Enable_and_start_the_Webwork2_Systemd_Service in the Installation Manual for 2.18 on Ubuntu]]. For networking changes to take effect, you should reboot the server.<br />
<br />
==Passwords==<br />
It is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access.<br />
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. Also change the mojolicious.yml secret.<br />
====Change the mojolicious.yml secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
====Change the password for wwadmin====<br />
<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$ <br />
'''Do not forget the new <code>&lt;wwadmin password&gt;</code> that you just entered.''' Below when we refer to <wwadmin password>, we mean the '''new''' <wwadmin password>.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = "wwadmin";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. We refer to this password as <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart webwork2 so the changes take effect.<br />
<br />
$ sudo systemctl restart webwork2<br />
[sudo] password for wwadmin: <wwadmin password><br />
$<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,authentication_string,password,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <code>webworkWrite</code> should have <br />
a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT Host, User, password FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
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.<br />
<br />
====Change the password for profa====<br />
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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
http://192.168.76.128/webwork2/admin</code> <br />
http://192.168.76.128/webwork2/mytestcourse</code> <br />
where of course you should use your actual ip address.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust the mojolicious.yml configuration according to your server's memory===<br />
Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. <br />
Search for the lines<br />
clients: 1<br />
workers: 10<br />
spare: 5<br />
and edit the numbers depending on the amount of RAM available on your server. Look at the recommendations for these settings in the section immediately above these lines in the webwork2.mojolicious.yml file<br />
<br />
Then save the file and Quit.<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in [[#Specific Virtual Environments|Specific Virtual Environments]] below. <br />
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<br />
20 GB to 30GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 19G 11G 7.3G 59% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/sda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 21.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags: <br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 20.0GB 20.0GB ext4<br />
<br />
(parted)<br />
<br />
We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command<br />
(parted) resizepart<br />
Partition number? 2<br />
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [20GB]? 30GB<br />
(parted)<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 31.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags:<br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 30.0GB 30.0GB ext4<br />
<br />
(parted)<br />
Notice we now have a 30 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below<br />
$ sudo resize2fs /dev/sda2<br />
[sudo] password for wwadmin: <wwadmin password><br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/sda2 is mounted on /; on-line resizing required<br />
old_desc_blocks = 2, new_desc_blocks = 3<br />
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 29G 11G 18G 38% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
*'''Option A''' is not implemented. '''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
==Specific Virtual Environments==<br />
Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of<br />
the specific environments we have information on:<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 15 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
<br />
===VMware Workstation 17 Player running on a Windows 11 host===<br />
====Importing the ova File====<br />
For VMware Player select Player, File, Open and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file.<br />
Name your machine and select a storage path and then hit Import<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
====Accessing your server from your host====<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the '''WeBWorK Placeholder Page'''. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the '''WeBWorK''' Welcome page. <br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 17 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Windows 11 host===<br />
<br />
====Importing the ova File====<br />
For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file. Click Finish. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Initially networking will be broken. Do the following from your guest WeBWorK system<br />
$ sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
...<br />
logical name: enp0s17<br />
version: 02<br />
serial: 08:00:27:30:28:b6<br />
...<br />
Remember the logical name from your system as we will need it below. We have to backup and then edit one file.<br />
<br />
$ cd /etc/netplan/<br />
$ sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak1<br />
[sudo] password for wwadmin: <wwadmin password> <br />
Now edit the <code> 00-installer-config.yaml</code> file<br />
$ sudo nano 00-installer-config.yaml<br />
It should look like (I had to stretch the window to see the whole file):<br />
# This is the network config written by 'subiquity'<br />
network:<br />
ethernets:<br />
ens33:<br />
dhcp4: true<br />
version: 2<br />
Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.<br />
<br />
<br />
Now reboot your server,e.g.<br />
$ sudo reboot<br />
[sudo] password for wwadmin: <wwadmin password> <br />
login and run the command<br />
$ ip address show<br />
and look at the output, something like<br />
... <br />
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000<br />
link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff<br />
inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17<br />
...<br />
<br />
We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below. <br />
<br />
In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network"<br />
Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:<br />
<br />
{| class="wikitable"<br />
|+Port Forwarding<br />
!Name<br />
!Protocol<br />
!Host IP<br />
!Host Port<br />
!Guest IP<br />
!Guest Port<br />
|-<br />
|ssh<br />
|TCP<br />
|127.0.0.1<br />
|2222<br />
|10.0.2.15<br />
|22<br />
|-<br />
|https<br />
|TCP<br />
|127.0.0.1<br />
|4443<br />
|10.0.2.15<br />
|443<br />
|-<br />
|http<br />
|TCP<br />
|127.0.0.1<br />
|8081<br />
|10.0.2.15<br />
|80<br />
|}<br />
Double check that you have entered everything correctly ('''using''' your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".<br />
<br />
Now boot your server.<br />
<br />
====Accessing your server from your host====<br />
We need to employ the port forwarding rules above.<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up with the port forwarding rules above, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and you should the '''WeBWorK''' Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.<br />
<br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your guest is shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list <br />
(probably "WW2.18_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. <br />
Click “Apply” when you're done.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host===<br />
<br />
====Importing the ova File====<br />
For VMware Player select File, Open a Virtual Machine and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and import the file.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
Accessing your server is exactly the same as in [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]] above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.76.128<br />
where of course you need to use the ip address of your WeBWorK guest server.<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 6 running on a Ubuntu 22.04 Desktop host===<br />
====Importing the ova File====<br />
Importing the ova File is exactly the same as in [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Accessing your server involves the same procedure as in [[#VirtualBox 6 running on a Windows 101 host|VirtualBox 6 running on a Windows 11 host]] above. So you have to<br />
# Find the name and MAC address of the virtual nic (network interface card)<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
# Set up port forwarding<br />
See [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above for details.<br />
<br />
'''Except''' that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh -p 2222 wwadmin@127.0.0.1<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
The procedure is the same as in [[#Expand the disk drive_2|Expand the disk drive]] the Windows 11 case above.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===QEMU/KVM running on a Ubuntu 22.04 Desktop host===<br />
====First install Qemu-KVM====<br />
<br />
It is probably a good idea to first update and upgrade the system packages:<br />
$ sudo apt update<br />
$ sudo apt upgrade<br />
<br />
Now install Qemu-KVM<br />
$ sudo apt install -y qemu-kvm virt-manager libvirt-daemon-system virtinst libvirt-clients bridge-utils<br />
<br />
Enable and start libvirtd<br />
$ sudo systemctl enable --now libvirtd<br />
$ sudo systemctl start libvirtd<br />
and check that all is OK<br />
$ sudo systemctl status libvirtd<br />
<br />
Now add wwadmin to the kvm and libvirt groups.<br />
$ sudo usermod -aG kvm $USER<br />
$ sudo usermod -aG libvirt $USER<br />
<br />
====Convert the image to qcow2 format====<br />
<br />
cd to whatever directory you downloaded the <code>WW2.18_Ubuntu22.04_Server.ova</code> file to (maybe "Downloads") and then untar it<br />
tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
which might take awhile. Then run the command to covert the vmdk format to qcow2 format<br />
qemu-img convert -p -f vmdk -O qcow2 WW2.18_Ubuntu22.04_Server-disk1.vmdk WW2.18_Ubuntu22.04_Server.qcow2<br />
and move the qcow2 image to the correct location<br />
sudo mv WW2.18_Ubuntu22.04_Server.qcow2 /var/lib/libvirt/images/<br />
<br />
====Boot up your virtual machine====<br />
Start up Virtual Machine Manager (search for VM in the app manager). Note that if you run into problems running the Virtual Machine Manager (e.g. QEMU/KVM not connected), the first thing to try is rebooting your host machine.<br />
<br />
In the Virtual Machine Manager,<br />
select File, New Virtual Machine, Import existing disk image, Forward, Browse and finally select WW2.18_Ubuntu22.04_Server.qcow2. The select Choose Volume and enter Ubuntu 22.04 LTS for the operating system you are installing. Next click Forward and choose your memory and CPUs. Select Forward again, name your system and finally select finish.<br />
<br />
Now log into your virtual machine (wwadmin with password wwadmin)<br />
<br />
====Networking====<br />
<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card), probably something like enp1s0<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details '''except that'''<br />
# You do not need port forwarding<br />
# Instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.122.233<br />
(where of course you need to use the actual ip address of your guest WeBWorK server).<br />
<br />
====Expand the disk drive====<br />
You can do most of this from the graphical Virtual Machine Manager (select the machine, then Edit, Virtual Machine Details). Below are commands to this from the command line. I think you have to actually expand the disk from the command line but you can get information and add cpu's and/or memory from the graphical Virtual Machine Manager.<br />
<br />
I'm assume the name of your WeBWorK guest is <code>wwserver</code> and it is Shutoff. First find the location of the disk.<br />
Run the command<br />
$ sudo virsh domblklist wwserver<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
Target Source<br />
-------------------------------------------------------------------------<br />
sda /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
<br />
Now get some info about the disk<br />
$ sudo qemu-img info /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
image: /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
file format: qcow2<br />
virtual size: 12 GiB (12884901888 bytes)<br />
disk size: 6.76 GiB<br />
cluster_size: 65536<br />
Format specific information:<br />
compat: 1.1<br />
lazy refcounts: false<br />
refcount bits: 16<br />
corrupt: false<br />
<br />
and now lets resize it to 20 GB by adding 8 GB<br />
sudo qemu-img resize /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2 +8G<br />
[sudo] password for wwadmin: <wwadmin password><br />
Image resized.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===Amazon EC2===<br />
While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the [[WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image]] is faster and easier anyway.<br />
<br />
==Debugging Networking Issues==<br />
If after reading the information above on networking you are still having problems, maybe the information below will be of help.<br />
<br />
===One method===<br />
There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms:<br />
$ ip address show<br />
does not return an ip address and the WW guest can not access the outside world.<br />
<br />
In VirtualBox I built another guest from the <code>ubuntu-22.04-live-server-amd64.iso</code> using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by<br />
sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files<br />
/etc/netplan/00-installer-config.yaml<br />
and<br />
/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg<br />
BUT in the WW guest the information did not agree. This led to the information given in [[#Networking_2|the Networking section of VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
===Ports on your WeBWorK guest===<br />
Run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you see something like<br />
<br />
systemd-r 697 systemd-resolve 13u IPv4 19596 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
sshd 772 root 3u IPv4 21834 0t0 TCP *:22 (LISTEN)<br />
sshd 772 root 4u IPv6 21845 0t0 TCP *:22 (LISTEN)<br />
lighttpd 810 www-data 4u IPv4 22509 0t0 TCP *:8080 (LISTEN)<br />
mysqld 856 mysql 31u IPv6 23312 0t0 TCP *:33060 (LISTEN)<br />
mysqld 856 mysql 33u IPv4 23654 0t0 TCP 127.0.0.1:3306 (LISTEN)<br />
Rserve 865 rserveuser 3u IPv4 22878 0t0 TCP 127.0.0.1:6311 (LISTEN)<br />
/usr/sbin 946 root 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 956 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 957 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 958 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 959 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 960 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
<br />
===Ports on your Windows 11 Pro host===<br />
Open a Power Shell command window as an administrator and run the command (it can take awhile)<br />
PS C:\> netstat -ab<br />
<br />
Active Connections<br />
<br />
Proto Local Address Foreign Address State<br />
TCP 0.0.0.0:135 desktop:0 LISTENING<br />
RpcSs<br />
[svchost.exe]<br />
TCP 0.0.0.0:443 desktop:0 LISTENING<br />
[vmware-hostd.exe]<br />
TCP 0.0.0.0:445 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:903 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:913 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:2869 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:3306 desktop:0 LISTENING<br />
[mysqld.exe]<br />
...<br />
TCP 0.0.0.0:6000 desktop:0 LISTENING<br />
[XWin_MobaX.exe]<br />
TCP 0.0.0.0:49664 desktop:0 LISTENING<br />
...<br />
TCP 127.0.0.1:2222 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52916 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52917 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:4443 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
...<br />
<br />
===Ports on your Linux host===<br />
<br />
Run the command<br />
<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for ****: <br />
<br />
and you should see something like the following<br />
systemd-r 436 systemd-resolve 13u IPv4 18620 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
vmware-au 1284 root 10u IPv6 33012 0t0 TCP *:902 (LISTEN)<br />
vmware-au 1284 root 11u IPv4 33013 0t0 TCP *:902 (LISTEN)<br />
sshd 8786 root 3u IPv4 114131 0t0 TCP *:22 (LISTEN)<br />
sshd 8786 root 4u IPv6 114133 0t0 TCP *:22 (LISTEN)<br />
cupsd 12124 root 6u IPv6 138503 0t0 TCP [::1]:631 (LISTEN)<br />
cupsd 12124 root 7u IPv4 138504 0t0 TCP 127.0.0.1:631 (LISTEN)<br />
VirtualBo 17065 wwadmin 48u IPv4 185297 0t0 TCP 127.0.0.1:8081 (LISTEN)<br />
VirtualBo 17065 wwadmin 49u IPv4 185298 0t0 TCP 127.0.0.1:4443 (LISTEN)<br />
VirtualBo 17065 wwadmin 50u IPv4 185299 0t0 TCP 127.0.0.1:8080 (LISTEN)<br />
VirtualBo 17065 wwadmin 51u IPv4 185300 0t0 TCP 127.0.0.1:2222 (LISTEN)<br />
<br />
Notice that port forwarding for VirtualBox has been set up correctly.<br />
<br />
<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Virtual_Machine_Image&diff=24166WeBWorK 2.18 Ubuntu Server 22.04 LTS Virtual Machine Image2023-09-11T17:47:26Z<p>Apizer: /* Networking */</p>
<hr />
<div><!--<br />
{{UnderConstruction}} <br />
--><br />
{{UnderConstruction}} <br />
These instructions cover the installation of the Ubuntu Server 22.04 LTS 64 bit operating system and WeBWorK 2.18 using the WeBWorK Virtual Machine Image. <br />
<br />
The WeBWorK Virtual Machine Image is an <code>.ova</code> file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, QEMU/KVM, etc. <br />
<br />
This image file has been tested on <br />
* VMware Workstation 17 Player<br />
* VirtualBox 7<br />
<br />
This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc.) installed and configured. <br />
<br />
== Installing from WW2.18 Ubuntu22.04 Server Virtual Machine Image ==<br />
<br />
===Overview===<br />
After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who has sudo privileges), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> who has professor privileges and also the Mjolicious secret (see below).<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]].<br />
<br />
===Download the ova image===<br />
<br />
Download the sha256 checksum and the .ova files from the WeBWorK Download Site below. <br />
<br />
You want to download the files <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code> and <code>WW2.18_Ubuntu22.04_Server.ova</code><br />
The ova is a 7.3 GB file.<br />
<br />
* [http://webwork.maa.org/ww-downloads/wwdownload.html WeBWorK Download Site]<br />
<br />
Verify the SHA256 checksum of your downloaded file <code>WW2.18_Ubuntu22.04_Server.ova</code> agrees with the one in <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code>.<br />
<br />
===OVA and OVF files===<br />
The <code>.ova</code> file is simply a tar bundle containing an <code>.ovf</code> file, one or more <code>.vmdk</code> files, a <code>.mf</code> file and possibly other files.<br />
* The <code>.ovf</code> file is an XML file which describes the packaged virtual machine and is human-readable. <br />
* The <code>.vmdk</code> file(s) contain the disk images(s).<br />
* Possibly other files<br />
* The <code>.mf</code> file contains SHA1 checksums for the above files.<br />
<br />
You can import a virtual machine either from an <code>.ova</code> file or from the <code>.ovf</code>, <code>.vmdk</code>, <code>.mf</code> collection. Sometimes importing from the <code>.ova</code> file may fail whereas importing from the <code>.ovf</code> or <code>.vmdk</code> file will succeed.<br />
<br />
You can extract the files in <code>WW2.18_Ubuntu22.04_Server.ova</code> with the command <br />
<br />
$ tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
<br />
You then can look at (and possibly edit) the human readable <code>WW2.18_Ubuntu22.04_Server.ofv</code> file. If you do edit the <code>WW2.18_Ubuntu22.04_Server.ofv</code> file, you will also have to compute the new SHA1 checksum and replace the old one in the <code>WW2.18_Ubuntu22.04_Server.mf</code> file for the files to be usable.<br />
<br />
===Installing the WeBWorK Virtual Machine Image ===<br />
<br />
Import the file <code>WW2.18_Ubuntu22.04_Server.ova</code> into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 17 Player <br />
running on a Windows 11 Pro host. It has been tested on <br />
* VMware Workstation 17 Player running on a Windows 11 host (Pro edition)<br />
* VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host<br />
* VirtualBox 7 running on a Windows 11 host (Home and Pro editions)<br />
* VirtualBox 6 running on a Ubuntu 22.04 Desktop host<br />
'''See [[#Specific Virtual Environments|Specific Virtual Environments]] below for installation information on specific virtual environments.'''<br />
<br />
====Processors, Memory, Hard Disk, Networking====<br />
The WeBWorK Virtual Machine Image was created with the following parameters:<br />
*20 GB dynamically allocated disk drive in VMDK format (single file) of which 13 GB is used<br />
*4 GB memory<br />
*2 cpu<br />
These resources are OK for testing and may suffice for a very small course but it is possible to overwhelm the machine. <br />
<br />
Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 17 Player running on a Windows 11 host). You should adjust these resources either when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk is more complicated. See [[#Specific Virtual Environments|Specific Virtual Environments]] below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see [[#Increase Disk Space|Increase Disk Space]] below). <br />
<br />
Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]) and/or look at [[#Debugging Networking Issues|Debugging Networking Issues]].<br />
<br />
===Import the .ova file===<br />
There may be specific information for your situation below. See<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
* [[#Amazon EC2|Amazon EC2]]<br />
<br />
===Your server===<br />
After importing, your virtual WeBWorK server will be identical to a system created by following the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] with the Webwork2 Mojolicious App being served directly via hypnotoad (option 1) and the Optional Configurations B and C implemented. '''Note that''' Option A (SSL) is not implemented (see [[#Set up WeBWorK to use SSL|Set up WeBWorK to use SSL]] below).<br />
<br />
'''Note''' that on some virtual environments, you may need to take additional actions. See the section [[#Specific Virtual Environments|Specific Virtual Environments]] below.<br />
<br />
You should read through the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] in order to understand how your server has been set up. Especially look at<br />
[[Installation Manual for 2.18 on Ubuntu#Notation|Notation in the Installation Manual for 2.18 on Ubuntu]] to understand the notation we use in these instructions.<br />
<br />
==Boot Your Server==<br />
===Log into your server ===<br />
After booting you should see a login prompt (you may have to press <code>&lt;Enter&gt;</code>).<br />
*Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges. We will denote<br />
wwadmin's password by <code><wwadmin password></code>. Initially this is set to <code>wwadmin</code>.<br />
If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.<br />
<br />
===Test your ip address===<br />
Run the command<br />
$ ip address show<br />
and look at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]). If that doesn't help look at [[#Debugging Networking Issues|Debugging Networking Issues]]. '''You have to fix this before you can go on to the next step'''.<br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program. <br />
<br />
You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with <code>copy</code> from the Edit menu or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit menu list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code> or <code>&lt;Shift&gt; &lt;Insert&gt;</code> depending on your application). <br />
<br />
My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. In any event, after testing, read the section [[#Make the WeBWorK Configuration Permanent|Make the WeBWorK Configuration Permanent]] below. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.<br />
<br />
I am assuming your network has been set up automatically.<br />
<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a <br />
terminal emulator running on your host using ssh, or from the terminal on the guest once you login. <br />
<br />
Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will probably see <br />
...<br />
Time zone: Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/New_York". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/New_York<br />
[sudo] password for wwadmin: <wwadmin password><br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
=== Checking for and Installing Hotfixes ===<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check_for_and_Install_Hotfixes in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
'''Important: The are bug fixes for both the webwork2 code and the pg code that occurred after the virtual machine image was built. You should definitely update both the webwork2 and pg code.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the virtual machine image was built. <br />
You should definitely update the webwork2 code.'''<br />
--><br />
<!--<br />
'''Important: The are bug fixes for the pg code that occurred after the virtual machine image was built. You should definitely update the pg code.'''<br />
--><br />
<br />
=== WeBWorK configuration ===<br />
<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
First we have to edit information about the network server setup. <br />
Search for <code>192.168.138.131</code> and replace that by your the new ip address you found above (<code>192.168.76.128</code> in our example above). <br />
<br />
'''But wait, this can be tricky'''. If you set up port forwarding (as we had to for VirtualBox), then instead use the code<br />
$server_root_url = 'http://localhost';<br />
<br />
The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM)<br />
<br />
$server_root_url = 'http://192.168.76.128';<br />
<br />
where of course your ip address may be different. The "http://" is important. <br />
<br />
'''Remark'''. First of all, let me admit I don't understand the above - it just works. If this is not set correctly (and I don't really understand what "correctly" means), then when you test the Library Browser, e.g. by clicking on <code>Library Browser</code> on the <code>Main Menu</code>, then on <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, you will not be able to select a <code>Chapter</code> and you will see an error message similar to<br />
183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.<br />
If you google this message, you will find a lot of people have seen this error and the most common reason is that <code>$server_root_url</code> has not been set correctly, whatever "correctly" means. A common error is to forget <code>http://</code> or to use <code>http://</code> when you should use <code>https://</code> (or vice versa) or to just have the wrong domain name or ip address.<br />
<br />
We now continue editing <code>site.conf</code> <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then.<br />
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.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.'''<br />
<br />
Then save the file and Quit. And restart the webwork2 app so that these changes take effect:<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
===Set up WeBWorK to use SSL===<br />
This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.<br />
<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Implement Option A (SSL)|Implement Option A (SSL) in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
Note that the Virtual Machine Image was built using Option 1: Serving Directly via Hypnotoad so that in the instructions for setting up SSL follow the section<br />
Set up Hypnotoad to use SSL (Option 1).<br />
<br />
===Finish up===<br />
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.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://192.168.76.128/webwork2</code> where of course you should use your actual ip address. If you have already set up https and haven't setup the redirect, then you should use <code>https://192.168.76.128/webwork2</code> . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.<br />
<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Make the WeBWorK Configuration Permanent==<br />
<br />
Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with <code>ip address show</code>) and used that when editing the <code>site.conf</code> file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.<br />
# The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the <code>site.conf</code> file. <br />
# The other method is to setup networking to use a fixed specific ip address for your server and use that in the <code>site.conf</code> file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the [[#Networking_2|Networking]] section under [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] below for information on editing these files. You can search the web for information on the correct syntax to use.<br />
<br />
Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections [[#Edit the site.conf file|Edit the site.conf file]] and [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]].<br />
<br />
Remember that any time you edit WeBWorK's configuration files, you have the restart the WeBWorK2 app for the changes to take effect; see [[Installation_Manual_for_2.18_on_Ubuntu#Enable_and_start_the_Webwork2_Systemd_Service|Enable_and_start_the_Webwork2_Systemd_Service in the Installation Manual for 2.18 on Ubuntu]]. For networking changes to take effect, you should reboot the server.<br />
<br />
==Passwords==<br />
It is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access.<br />
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. Also change the mojolicious.yml secret.<br />
====Change the mojolicious.yml secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
====Change the password for wwadmin====<br />
<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$ <br />
'''Do not forget the new <code>&lt;wwadmin password&gt;</code> that you just entered.''' Below when we refer to <wwadmin password>, we mean the '''new''' <wwadmin password>.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = "wwadmin";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. We refer to this password as <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart webwork2 so the changes take effect.<br />
<br />
$ sudo systemctl restart webwork2<br />
[sudo] password for wwadmin: <wwadmin password><br />
$<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,authentication_string,password,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <code>webworkWrite</code> should have <br />
a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT Host, User, password FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
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.<br />
<br />
====Change the password for profa====<br />
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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
http://192.168.76.128/webwork2/admin</code> <br />
http://192.168.76.128/webwork2/mytestcourse</code> <br />
where of course you should use your actual ip address.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust the mojolicious.yml configuration according to your server's memory===<br />
Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. <br />
Search for the lines<br />
clients: 1<br />
workers: 10<br />
spare: 5<br />
and edit the numbers depending on the amount of RAM available on your server. Look at the recommendations for these settings in the section immediately above these lines in the webwork2.mojolicious.yml file<br />
<br />
Then save the file and Quit.<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in [[#Specific Virtual Environments|Specific Virtual Environments]] below. <br />
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<br />
20 GB to 30GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 19G 11G 7.3G 59% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/sda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 21.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags: <br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 20.0GB 20.0GB ext4<br />
<br />
(parted)<br />
<br />
We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command<br />
(parted) resizepart<br />
Partition number? 2<br />
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [20GB]? 30GB<br />
(parted)<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 31.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags:<br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 30.0GB 30.0GB ext4<br />
<br />
(parted)<br />
Notice we now have a 30 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below<br />
$ sudo resize2fs /dev/sda2<br />
[sudo] password for wwadmin: <wwadmin password><br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/sda2 is mounted on /; on-line resizing required<br />
old_desc_blocks = 2, new_desc_blocks = 3<br />
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 29G 11G 18G 38% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
*'''Option A''' is not implemented. '''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
==Specific Virtual Environments==<br />
Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of<br />
the specific environments we have information on:<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 15 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
<br />
===VMware Workstation 17 Player running on a Windows 11 host===<br />
====Importing the ova File====<br />
For VMware Player select Player, File, Open and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file.<br />
Name your machine and select a storage path and then hit Import<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
====Accessing your server from your host====<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the '''WeBWorK Placeholder Page'''. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the '''WeBWorK''' Welcome page. <br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 17 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Windows 11 host===<br />
<br />
====Importing the ova File====<br />
For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file. Click Finish. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Initially networking will be broken. Do the following from your guest WeBWorK system<br />
$ sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
...<br />
logical name: enp0s17<br />
version: 02<br />
serial: 08:00:27:30:28:b6<br />
...<br />
Remember the logical name from your system as we will need it below. We have to backup and then edit one file.<br />
<br />
$ cd /etc/netplan/<br />
$ sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak1<br />
[sudo] password for wwadmin: <wwadmin password> <br />
Now edit the <code> 00-installer-config.yaml</code> file<br />
$ sudo nano 00-installer-config.yaml<br />
It should look like (I had to stretch the window to see the whole file):<br />
# This is the network config written by 'subiquity'<br />
network:<br />
ethernets:<br />
ens33:<br />
dhcp4: true<br />
version: 2<br />
Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.<br />
<br />
<br />
Now reboot your server,e.g.<br />
$ sudo reboot<br />
[sudo] password for wwadmin: <wwadmin password> <br />
login and run the command<br />
$ ip address show<br />
and look at the output, something like<br />
... <br />
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000<br />
link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff<br />
inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17<br />
...<br />
<br />
We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below. <br />
<br />
In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network"<br />
Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:<br />
<br />
{| class="wikitable"<br />
|+Port Forwarding<br />
!Name<br />
!Protocol<br />
!Host IP<br />
!Host Port<br />
!Guest IP<br />
!Guest Port<br />
|-<br />
|ssh<br />
|TCP<br />
|127.0.0.1<br />
|2222<br />
|10.0.2.15<br />
|22<br />
|-<br />
|https<br />
|TCP<br />
|127.0.0.1<br />
|4443<br />
|10.0.2.15<br />
|443<br />
|-<br />
|http<br />
|TCP<br />
|127.0.0.1<br />
|8081<br />
|10.0.2.15<br />
|80<br />
|}<br />
Double check that you have entered everything correctly ('''using''' your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".<br />
<br />
Now boot your server.<br />
<br />
====Accessing your server from your host====<br />
We need to employ the port forwarding rules above.<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up with the port forwarding rules above, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and you should the '''WeBWorK''' Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.<br />
<br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your guest is shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list <br />
(probably "WW2.18_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. <br />
Click “Apply” when you're done.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host===<br />
<br />
====Importing the ova File====<br />
For VMware Player select File, Open a Virtual Machine and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and import the file.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
Accessing your server is exactly the same as in [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]] above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.76.128<br />
where of course you need to use the ip address of your WeBWorK guest server.<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 6 running on a Ubuntu 22.04 Desktop host===<br />
====Importing the ova File====<br />
Importing the ova File is exactly the same as in [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Accessing your server involves the same procedure as in [[#VirtualBox 6 running on a Windows 101 host|VirtualBox 6 running on a Windows 11 host]] above. So you have to<br />
# Find the name and MAC address of the virtual nic (network interface card)<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
# Set up port forwarding<br />
See [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above for details.<br />
<br />
'''Except''' that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh -p 2222 wwadmin@127.0.0.1<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
The procedure is the same as in [[#Expand the disk drive_2|Expand the disk drive]] the Windows 11 case above.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===QEMU/KVM running on a Ubuntu 22.04 Desktop host===<br />
====First install Qemu-KVM====<br />
<br />
It is probably a good idea to first update and upgrade the system packages:<br />
$ sudo apt update<br />
$ sudo apt upgrade<br />
<br />
Now install Qemu-KVM<br />
$ sudo apt install -y qemu-kvm virt-manager libvirt-daemon-system virtinst libvirt-clients bridge-utils<br />
<br />
Enable and start libvirtd<br />
$ sudo systemctl enable --now libvirtd<br />
$ sudo systemctl start libvirtd<br />
and check that all is OK<br />
$ sudo systemctl status libvirtd<br />
<br />
Now add wwadmin to the kvm and libvirt groups.<br />
$ sudo usermod -aG kvm $USER<br />
$ sudo usermod -aG libvirt $USER<br />
<br />
====Convert the image to qcow2 format====<br />
<br />
cd to whatever directory you downloaded the <code>WW2.18_Ubuntu22.04_Server.ova</code> file to (maybe "Downloads") and then untar it<br />
tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
which might take awhile. Then run the command to covert the vmdk format to qcow2 format<br />
qemu-img convert -p -f vmdk -O qcow2 WW2.18_Ubuntu22.04_Server-disk1.vmdk WW2.18_Ubuntu22.04_Server.qcow2<br />
and move the qcow2 image to the correct location<br />
sudo mv WW2.18_Ubuntu22.04_Server.qcow2 /var/lib/libvirt/images/<br />
<br />
====Boot up your virtual machine====<br />
Start up Virtual Machine Manager (search for VM in the app manager). Note that if you run into problems running the Virtual Machine Manager (e.g. QEMU/KVM not connected), the first thing to try is rebooting your host machine.<br />
<br />
In the Virtual Machine Manager,<br />
select File, New Virtual Machine, Import existing disk image, Forward, Browse and finally select WW2.18_Ubuntu22.04_Server.qcow2. The select Choose Volume and enter Ubuntu 22.04 LTS for the operating system you are installing. Next click Forward and choose your memory and CPUs. Select Forward again, name your system and finally select finish.<br />
<br />
Now log into your virtual machine (wwadmin with password wwadmin)<br />
<br />
====Networking====<br />
<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card), probably something like enp1s0<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details '''except that'''<br />
# You do not need port forwarding<br />
# Instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.122.233<br />
(where of course you need to use the actual ip address of your guest WeBWorK server).<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
You can do most of this from the graphical Virtual Machine Manager (select the machine, then Edit, Virtual Machine Details). Below are commands to this from the command line. I think you have to actually expand the disk from the command line but you can get information and add cpu's and/or memory from the graphical Virtual Machine Manager.<br />
<br />
I'm assume the name of your WeBWorK guest is <code>wwserver</code> and it is Shutoff. First find the location of the disk.<br />
Run the command<br />
$ sudo virsh domblklist wwserver<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
Target Source<br />
-------------------------------------------------------------------------<br />
sda /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
<br />
Now get some info about the disk<br />
$ sudo qemu-img info /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
image: /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
file format: qcow2<br />
virtual size: 12 GiB (12884901888 bytes)<br />
disk size: 6.76 GiB<br />
cluster_size: 65536<br />
Format specific information:<br />
compat: 1.1<br />
lazy refcounts: false<br />
refcount bits: 16<br />
corrupt: false<br />
<br />
and now lets resize it to 20 GB by adding 8 GB<br />
sudo qemu-img resize /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2 +8G<br />
[sudo] password for wwadmin: <wwadmin password><br />
Image resized.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===Amazon EC2===<br />
While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the [[WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image]] is faster and easier anyway.<br />
<br />
==Debugging Networking Issues==<br />
If after reading the information above on networking you are still having problems, maybe the information below will be of help.<br />
<br />
===One method===<br />
There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms:<br />
$ ip address show<br />
does not return an ip address and the WW guest can not access the outside world.<br />
<br />
In VirtualBox I built another guest from the <code>ubuntu-22.04-live-server-amd64.iso</code> using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by<br />
sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files<br />
/etc/netplan/00-installer-config.yaml<br />
and<br />
/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg<br />
BUT in the WW guest the information did not agree. This led to the information given in [[#Networking_2|the Networking section of VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
===Ports on your WeBWorK guest===<br />
Run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you see something like<br />
<br />
systemd-r 697 systemd-resolve 13u IPv4 19596 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
sshd 772 root 3u IPv4 21834 0t0 TCP *:22 (LISTEN)<br />
sshd 772 root 4u IPv6 21845 0t0 TCP *:22 (LISTEN)<br />
lighttpd 810 www-data 4u IPv4 22509 0t0 TCP *:8080 (LISTEN)<br />
mysqld 856 mysql 31u IPv6 23312 0t0 TCP *:33060 (LISTEN)<br />
mysqld 856 mysql 33u IPv4 23654 0t0 TCP 127.0.0.1:3306 (LISTEN)<br />
Rserve 865 rserveuser 3u IPv4 22878 0t0 TCP 127.0.0.1:6311 (LISTEN)<br />
/usr/sbin 946 root 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 956 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 957 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 958 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 959 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 960 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
<br />
===Ports on your Windows 11 Pro host===<br />
Open a Power Shell command window as an administrator and run the command (it can take awhile)<br />
PS C:\> netstat -ab<br />
<br />
Active Connections<br />
<br />
Proto Local Address Foreign Address State<br />
TCP 0.0.0.0:135 desktop:0 LISTENING<br />
RpcSs<br />
[svchost.exe]<br />
TCP 0.0.0.0:443 desktop:0 LISTENING<br />
[vmware-hostd.exe]<br />
TCP 0.0.0.0:445 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:903 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:913 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:2869 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:3306 desktop:0 LISTENING<br />
[mysqld.exe]<br />
...<br />
TCP 0.0.0.0:6000 desktop:0 LISTENING<br />
[XWin_MobaX.exe]<br />
TCP 0.0.0.0:49664 desktop:0 LISTENING<br />
...<br />
TCP 127.0.0.1:2222 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52916 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52917 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:4443 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
...<br />
<br />
===Ports on your Linux host===<br />
<br />
Run the command<br />
<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for ****: <br />
<br />
and you should see something like the following<br />
systemd-r 436 systemd-resolve 13u IPv4 18620 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
vmware-au 1284 root 10u IPv6 33012 0t0 TCP *:902 (LISTEN)<br />
vmware-au 1284 root 11u IPv4 33013 0t0 TCP *:902 (LISTEN)<br />
sshd 8786 root 3u IPv4 114131 0t0 TCP *:22 (LISTEN)<br />
sshd 8786 root 4u IPv6 114133 0t0 TCP *:22 (LISTEN)<br />
cupsd 12124 root 6u IPv6 138503 0t0 TCP [::1]:631 (LISTEN)<br />
cupsd 12124 root 7u IPv4 138504 0t0 TCP 127.0.0.1:631 (LISTEN)<br />
VirtualBo 17065 wwadmin 48u IPv4 185297 0t0 TCP 127.0.0.1:8081 (LISTEN)<br />
VirtualBo 17065 wwadmin 49u IPv4 185298 0t0 TCP 127.0.0.1:4443 (LISTEN)<br />
VirtualBo 17065 wwadmin 50u IPv4 185299 0t0 TCP 127.0.0.1:8080 (LISTEN)<br />
VirtualBo 17065 wwadmin 51u IPv4 185300 0t0 TCP 127.0.0.1:2222 (LISTEN)<br />
<br />
Notice that port forwarding for VirtualBox has been set up correctly.<br />
<br />
<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]]</div>Apizerhttps://webwork.maa.org/mediawiki_new/index.php?title=WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Virtual_Machine_Image&diff=24165WeBWorK 2.18 Ubuntu Server 22.04 LTS Virtual Machine Image2023-09-11T17:46:46Z<p>Apizer: /* Networking */</p>
<hr />
<div><!--<br />
{{UnderConstruction}} <br />
--><br />
{{UnderConstruction}} <br />
These instructions cover the installation of the Ubuntu Server 22.04 LTS 64 bit operating system and WeBWorK 2.18 using the WeBWorK Virtual Machine Image. <br />
<br />
The WeBWorK Virtual Machine Image is an <code>.ova</code> file which is an "open, secure, portable, efficient and extensible format for the packaging and distribution of software to be run in virtual machines" (see http://en.wikipedia.org/wiki/Open_Virtualization_Format) and is supported by VMware, VirtualBox, QEMU/KVM, etc. <br />
<br />
This image file has been tested on <br />
* VMware Workstation 17 Player<br />
* VirtualBox 7<br />
<br />
This "server" version contains everything you need to run a WeBWorK server (e.g. WeBWorK, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc.) installed and configured. <br />
<br />
== Installing from WW2.18 Ubuntu22.04 Server Virtual Machine Image ==<br />
<br />
===Overview===<br />
After installing from the WeBWorK Virtual Machine Image, you will have a full fledged Ubuntu Server 22.04 LTS system with WeBWorK 2.18, Mjolicious/hypnotoad, MariaDB, R server, log rotation, etc. installed and configured. If your network uses DHCP, networking will be automatically configured for your system. If it uses static IP addresses, you will have to configure networking. Also it is imperative that you CHANGE THE PASSWORDS for the OS user <code>wwadmin</code> (who has sudo privileges), for the MariaDB user <code>webworkWrite</code> who has access to MariaDB, for the WeBWorK user <code>admin</code> who has admin privileges and for the WeBWorK user <code>profa</code> who has professor privileges and also the Mjolicious secret (see below).<br />
<br />
There are more detailed instructions for Ubuntu Server 22.04 and WeBWorK 2.18 at<br />
[[Installation_Manual_for_2.18_on_Ubuntu|Installation Manual for 2.18 on Ubuntu]].<br />
<br />
===Download the ova image===<br />
<br />
Download the sha256 checksum and the .ova files from the WeBWorK Download Site below. <br />
<br />
You want to download the files <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code> and <code>WW2.18_Ubuntu22.04_Server.ova</code><br />
The ova is a 7.3 GB file.<br />
<br />
* [http://webwork.maa.org/ww-downloads/wwdownload.html WeBWorK Download Site]<br />
<br />
Verify the SHA256 checksum of your downloaded file <code>WW2.18_Ubuntu22.04_Server.ova</code> agrees with the one in <code>WW2.18_Ubuntu22.04_Server.ova.sha256</code>.<br />
<br />
===OVA and OVF files===<br />
The <code>.ova</code> file is simply a tar bundle containing an <code>.ovf</code> file, one or more <code>.vmdk</code> files, a <code>.mf</code> file and possibly other files.<br />
* The <code>.ovf</code> file is an XML file which describes the packaged virtual machine and is human-readable. <br />
* The <code>.vmdk</code> file(s) contain the disk images(s).<br />
* Possibly other files<br />
* The <code>.mf</code> file contains SHA1 checksums for the above files.<br />
<br />
You can import a virtual machine either from an <code>.ova</code> file or from the <code>.ovf</code>, <code>.vmdk</code>, <code>.mf</code> collection. Sometimes importing from the <code>.ova</code> file may fail whereas importing from the <code>.ovf</code> or <code>.vmdk</code> file will succeed.<br />
<br />
You can extract the files in <code>WW2.18_Ubuntu22.04_Server.ova</code> with the command <br />
<br />
$ tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
<br />
You then can look at (and possibly edit) the human readable <code>WW2.18_Ubuntu22.04_Server.ofv</code> file. If you do edit the <code>WW2.18_Ubuntu22.04_Server.ofv</code> file, you will also have to compute the new SHA1 checksum and replace the old one in the <code>WW2.18_Ubuntu22.04_Server.mf</code> file for the files to be usable.<br />
<br />
===Installing the WeBWorK Virtual Machine Image ===<br />
<br />
Import the file <code>WW2.18_Ubuntu22.04_Server.ova</code> into your virtualization software package (e.g. VMware, VirtualBox, QEMU/KVM). The ova file was created on VMware Workstation 17 Player <br />
running on a Windows 11 Pro host. It has been tested on <br />
* VMware Workstation 17 Player running on a Windows 11 host (Pro edition)<br />
* VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host<br />
* VirtualBox 7 running on a Windows 11 host (Home and Pro editions)<br />
* VirtualBox 6 running on a Ubuntu 22.04 Desktop host<br />
'''See [[#Specific Virtual Environments|Specific Virtual Environments]] below for installation information on specific virtual environments.'''<br />
<br />
====Processors, Memory, Hard Disk, Networking====<br />
The WeBWorK Virtual Machine Image was created with the following parameters:<br />
*20 GB dynamically allocated disk drive in VMDK format (single file) of which 13 GB is used<br />
*4 GB memory<br />
*2 cpu<br />
These resources are OK for testing and may suffice for a very small course but it is possible to overwhelm the machine. <br />
<br />
Assuming you have not changed things when importing the image, some of these configurations may remain in effect (they all will for VMware Workstation 17 Player running on a Windows 11 host). You should adjust these resources either when you import the .ova file or later after you have tested things. Adjusting the number of processors and memory should be straightforward. Expanding the hard disk is more complicated. See [[#Specific Virtual Environments|Specific Virtual Environments]] below and also consult the documentation for your virtual machine environment. After you have expanded the disk drive, you will still have to make the extra space available to Ubuntu (see [[#Increase Disk Space|Increase Disk Space]] below). <br />
<br />
Setting up networking may be the most tricky part. If you have problems, look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]) and/or look at [[#Debugging Networking Issues|Debugging Networking Issues]].<br />
<br />
===Import the .ova file===<br />
There may be specific information for your situation below. See<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
* [[#Amazon EC2|Amazon EC2]]<br />
<br />
===Your server===<br />
After importing, your virtual WeBWorK server will be identical to a system created by following the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] with the Webwork2 Mojolicious App being served directly via hypnotoad (option 1) and the Optional Configurations B and C implemented. '''Note that''' Option A (SSL) is not implemented (see [[#Set up WeBWorK to use SSL|Set up WeBWorK to use SSL]] below).<br />
<br />
'''Note''' that on some virtual environments, you may need to take additional actions. See the section [[#Specific Virtual Environments|Specific Virtual Environments]] below.<br />
<br />
You should read through the instructions [[Installation Manual for 2.18 on Ubuntu|Installation Manual for 2.18 on Ubuntu]] in order to understand how your server has been set up. Especially look at<br />
[[Installation Manual for 2.18 on Ubuntu#Notation|Notation in the Installation Manual for 2.18 on Ubuntu]] to understand the notation we use in these instructions.<br />
<br />
==Boot Your Server==<br />
===Log into your server ===<br />
After booting you should see a login prompt (you may have to press <code>&lt;Enter&gt;</code>).<br />
*Log in as "wwadmin" with the password "wwadmin" (more on accounts and passwords below). "wwadmin" has sudo privileges. We will denote<br />
wwadmin's password by <code><wwadmin password></code>. Initially this is set to <code>wwadmin</code>.<br />
If your network uses DHCP, networking may be automatically configured for your system (but you may have to edit some files, see below). If not you will have to set it up manually.<br />
<br />
===Test your ip address===<br />
Run the command<br />
$ ip address show<br />
and look at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If you do not see the ip address, you have a networking problem which is not unusual at this point. More specifically, you should not have a problem using VMWare, but will have a problem using VirtualBox or QEMU/KVM. Look at the "Networking" section under your specific environment below see ([[#Specific Virtual Environments|Specific Virtual Environments]]). If that doesn't help look at [[#Debugging Networking Issues|Debugging Networking Issues]]. '''You have to fix this before you can go on to the next step'''.<br />
<br />
=== Accessing Your Server from a Terminal Emulator on your Host ===<br />
At this point you can login to your server from your host machine using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are) using your favourite terminal emulator program. <br />
<br />
You can do all of the remaining installation from a terminal emulator on your host. The advantage of doing this is that you can copy commands from these instructions (with <code>copy</code> from the Edit menu or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit menu list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code> or <code>&lt;Shift&gt; &lt;Insert&gt;</code> depending on your application). <br />
<br />
My advice is to first test accessing your server from your host machine and check that everything is working properly. We will do this with using the NAT network adapter and your new server's ip address (not domain name). This is fine for testing but is not a good permanent solution. After testing that WeBWorK is working properly, if you want to allow access from the web (e.g. if you will have students using the system) you can reconfigure your system using a suitable network adapter and you new server's registered domain name. In any event, after testing, read the section [[#Make the WeBWorK Configuration Permanent|Make the WeBWorK Configuration Permanent]] below. For the most part, instructions on allowing access from the web are beyond the scope of this document. Here we give instructions on accessing your server from your host machine.<br />
<br />
I am assuming your network has been set up automatically.<br />
<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
If your system is set up with NAT using these rules it means that at this point you can only access your server from a web browser running on your host machine, from a <br />
terminal emulator running on your host using ssh, or from the terminal on the guest once you login. <br />
<br />
Actually establishing the connection depends on both your virtual machine environment and your host environment. Look at the documentation below for your situation.<br />
* [[#VMware Workstation 17 Player running on a Windows 11 host|VMware Workstation 17 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
===Set the Timezone for your server===<br />
To find out what timezone your server is set to run the command<br />
$ timedatectl<br />
and you will probably see <br />
...<br />
Time zone: Time zone: Etc/UTC (UTC, +0000)<br />
...<br />
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<br />
$ timedatectl list-timezones<br />
Look through the list and find your timezone, e.g. "America/New_York". Then set the timezone (you have to be root), e.g.<br />
$ sudo timedatectl set-timezone America/New_York<br />
[sudo] password for wwadmin: <wwadmin password><br />
and then<br />
$ timedatectl<br />
to check it was set correctly.<br />
<br />
=== Checking for and Installing Hotfixes ===<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Check_for_and_Install_Hotfixes|Check_for_and_Install_Hotfixes in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
'''Important: The are bug fixes for both the webwork2 code and the pg code that occurred after the virtual machine image was built. You should definitely update both the webwork2 and pg code.'''<br />
<br />
<br />
<!--<br />
'''Important: The are bug fixes for the webwork2 code that occurred after the virtual machine image was built. <br />
You should definitely update the webwork2 code.'''<br />
--><br />
<!--<br />
'''Important: The are bug fixes for the pg code that occurred after the virtual machine image was built. You should definitely update the pg code.'''<br />
--><br />
<br />
=== WeBWorK configuration ===<br />
<br />
Most WeBWorK configuration is done in the files <code>/opt/webwork/webwork2/conf/site.conf</code> and <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>localOverrides.conf</code>) in the <code>course.conf</code> file. An instructor can only edit the <code>course.conf</code> 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.<br />
<br />
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).<br />
<br />
Actually there are three main configuration files, <code>site.conf</code>, <code>defaults.config</code> and <code>localOverrides.conf</code>. The reason there are three configuration files is to make upgrading WeBWorK easier.<br />
<br />
* <code>site.conf</code>: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, <code>site.conf.dist</code> will be.<br />
* <code>defaults.config</code>: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.<br />
* <code>localOverrides.conf</code> This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, <code>localOverrides.conf.dist</code> will be.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. <br />
<br />
====Edit the site.conf file====<br />
Now backup and edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf site.conf.bak1<br />
$ nano site.conf<br />
<br />
First we have to edit information about the network server setup. <br />
Search for <code>192.168.138.131</code> and replace that by your the new ip address you found above (<code>192.168.76.128</code> in our example above). <br />
<br />
'''But wait, this can be tricky'''. If you set up port forwarding (as we had to for VirtualBox), then instead use the code<br />
$server_root_url = 'http://localhost';<br />
<br />
The edited line should look like the above line when we use port forwarding (i.e. running under VirtualBox) and like the line below when there is no port forwarding (i.e. running under VMware or QEMU/KVM)<br />
<br />
$server_root_url = 'http://192.168.76.128';<br />
<br />
where of course your ip address may be different. The "http://" is important. <br />
<br />
'''Remark'''. First of all, let me admit I don't understand the above - it just works. If this is not set correctly (and I don't really understand what "correctly" means), then when you test the Library Browser, e.g. by clicking on <code>Library Browser</code> on the <code>Main Menu</code>, then on <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, you will not be able to select a <code>Chapter</code> and you will see an error message similar to<br />
183 setmaker.js: /webwork2/instructorXMLHandler: Forbidden.<br />
If you google this message, you will find a lot of people have seen this error and the most common reason is that <code>$server_root_url</code> has not been set correctly, whatever "correctly" means. A common error is to forget <code>http://</code> or to use <code>http://</code> when you should use <code>https://</code> (or vice versa) or to just have the wrong domain name or ip address.<br />
<br />
We now continue editing <code>site.conf</code> <br />
<br />
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<br />
timedatectl list-timezones<br />
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 <code>America/New_York</code> and you should enter <code>$siteDefaults{timezone} = "America/New_York";</code> which is the default. Read the documentation in this section of the the <code>site.conf</code> file for more information on selecting time zones and formatting dates. <br />
<br />
Search for <code>$siteDefaults{timezone}</code> and enter your local timezone if it is not correct.<br />
<br />
Here is some information on email although this probably won't really work until you connect WeBWorK to the outside world. You might want to hold off on this until then.<br />
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.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configure one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = ''; # e.g. 'mail.yourschool.edu' or 'localhost'<br />
$mail{smtpSender} = ''; # e.g. 'webwork@yourserver.yourschool.edu'<br />
<br />
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.'''<br />
<br />
Then save the file and Quit. And restart the webwork2 app so that these changes take effect:<br />
$ sudo systemctl restart webwork2<br />
<br />
==== The defaults.config file ====<br />
<br />
The <code>defaults.config</code> 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 <code>localOverrides.conf</code> file using the same syntax as in the <code>defaults.config</code> file.<br />
<br />
===Set up WeBWorK to use SSL===<br />
This step configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. It is optional but you should certainly do this if students will be using your server. However, I would hold off on this until you have tested that everything is working properly.<br />
<br />
Follow the instructions at [[Installation_Manual_for_2.18_on_Ubuntu#Implement Option A (SSL)|Implement Option A (SSL) in the Installation Manual for 2.18 on Ubuntu]].<br />
<br />
Note that the Virtual Machine Image was built using Option 1: Serving Directly via Hypnotoad so that in the instructions for setting up SSL follow the section<br />
Set up Hypnotoad to use SSL (Option 1).<br />
<br />
===Finish up===<br />
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.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
Connect to <code>http://192.168.76.128/webwork2</code> where of course you should use your actual ip address. If you have already set up https and haven't setup the redirect, then you should use <code>https://192.168.76.128/webwork2</code> . If you are not using official certificates, your browser should report than the connection is unsafe so you may have to choose to proceed.<br />
<br />
<br />
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 <code>/opt/webwork/webwork2/logs/webwork2.log</code>. And you should look at [[Installation_Manual_for_2.18_on_Ubuntu#Test_that_Things_are_Working_Properly|Test that Things are Working Properly in the Installation Manual for 2.18 on Ubuntu]]<br />
for help.<br />
<br />
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).<br />
<br />
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.<br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. 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.<br />
<br />
Next click on <code>Problem List</code> to bring back the Problem List Page and click on <code>Download PDF ...</code>. 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 <code>Generate hardcopy for selected users and selected sets</code>. <br />
<br />
Look through the problems in the other sets.<br />
<br />
Now test the Library Browser. Click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out) <br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed.<br />
<br />
Next test that WeBWorK problems using R run properly. You are already in the Library Browser.<br />
Select "Statistics" as <code>Subject</code>, "Bayesian inference" as <code>Chapter</code> and "Posterior distribution" as <code>Section</code> and then hit <code>View Problems</code>. <br />
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.<br />
<br />
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.<br />
<br />
==Make the WeBWorK Configuration Permanent==<br />
<br />
Now that everything is working properly, it is time to make the WeBWorK configuration permanent. We configured WeBWorK using your WeBWorK guest server's current ip address (found with <code>ip address show</code>) and used that when editing the <code>site.conf</code> file. Since the network is setup with DHCP enabled, it means that the current ip address is not permanent. If it changes, WeBWorK will break. We have two options to fix this.<br />
# The preferred method is to use the registered domain name for your WeBWorK system in place of the ip address in the one place it occurs in the <code>site.conf</code> file. <br />
# The other method is to setup networking to use a fixed specific ip address for your server and use that in the <code>site.conf</code> file. For this your have to edit the 00-installer-config.yaml and cloud.cfg.d files. See the [[#Networking_2|Networking]] section under [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] below for information on editing these files. You can search the web for information on the correct syntax to use.<br />
<br />
Also if you are still using port forwarding (which you shouldn't in a permanent installation), things get more complicated as seen above in the sections [[#Edit the site.conf file|Edit the site.conf file]] and [[#Edit the localOverrides.conf file|Edit the localOverrides.conf file]].<br />
<br />
Remember that any time you edit WeBWorK's configuration files, you have the restart the WeBWorK2 app for the changes to take effect; see [[Installation_Manual_for_2.18_on_Ubuntu#Enable_and_start_the_Webwork2_Systemd_Service|Enable_and_start_the_Webwork2_Systemd_Service in the Installation Manual for 2.18 on Ubuntu]]. For networking changes to take effect, you should reboot the server.<br />
<br />
==Passwords==<br />
It is '''IMPERATIVE''' that you CHANGE THE PASSWORD for the OS user wwadmin (who has sudo privileges). Otherwise anyone can connect to your server and pretty easily gain root access.<br />
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. Also change the mojolicious.yml secret.<br />
====Change the mojolicious.yml secret====<br />
Edit <code>/opt/webwork/webwork2/conf/webwork2.mojolicious.yml</code> 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.<br />
<br />
====Change the password for wwadmin====<br />
<br />
$ passwd<br />
Changing passwd for wwadmin:<br />
(current) UNIX password: wwadmin<br />
Enter new UNIX password: <code>&lt;new wwadmin password&gt;</code> <br />
Retype new UNIX password: <code>&lt;new wwadmin password&gt;</code><br />
passwd: password update successfully<br />
$ <br />
'''Do not forget the new <code>&lt;wwadmin password&gt;</code> that you just entered.''' Below when we refer to <wwadmin password>, we mean the '''new''' <wwadmin password>.<br />
<br />
====Change the password for webworkWrite====<br />
Now we change the passwords for the MariaDB user <code>webworkWrite</code>. First we edit <code>site.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
Search for <code>$database_password = "wwadmin";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. We refer to this password as <code>&lt;database_password&gt;</code>. Remember it as we will need it shortly. Then save the file and Quit.<br />
<br />
Then restart webwork2 so the changes take effect.<br />
<br />
$ sudo systemctl restart webwork2<br />
[sudo] password for wwadmin: <wwadmin password><br />
$<br />
<br />
and start MariaDB<br />
<br />
$ sudo mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
<br />
Now lets check the MariaDB users.<br />
<br />
MariaDB> SELECT user,authentication_string,password,plugin,host FROM mysql.user;<br />
<br />
You will see a table with four users. <code>webworkWrite</code> should have <br />
a valid password (which will be displayed in encrypted form). <br />
<br />
Now we will change the password for the <code>webworkWrite</code> User <br />
<br />
MariaDB> ALTER USER 'webworkWrite'@'localhost' IDENTIFIED BY '<database_password>';<br />
where of course you should replace <code>&lt;database_password&gt;</code> by whatever you used above (use the single quotes but no angle braces). Then<br />
MariaDB> FLUSH PRIVILEGES;<br />
use your up arrow key to run the command<br />
MariaDB> SELECT Host, User, password FROM mysql.user;<br />
and you should see that <code>webworkWrite</code> has a new passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MariaDB<br />
<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
If you want to check that you set the password correctly, do the following:<br />
mysql -u webworkWrite -p -h127.0.0.1 --protocol=tcp<br />
Enter password: <database_password><br />
and you should see<br />
Welcome to the MariaDB monitor ...<br />
MariaDB><br />
Now exit<br />
MariaDB> exit<br />
Bye<br />
$<br />
<br />
====Change the password for admin====<br />
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.<br />
<br />
====Change the password for profa====<br />
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.<br />
<br />
====Change the password for jsmith====<br />
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.<br />
<br />
==More House Keeping==<br />
<br />
===Hide the admin and myTestCourse courses===<br />
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.<br />
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 <br />
access these courses directly by<br />
http://192.168.76.128/webwork2/admin</code> <br />
http://192.168.76.128/webwork2/mytestcourse</code> <br />
where of course you should use your actual ip address.<br />
===Institution Logo===<br />
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.<br />
<br />
All you need to do is add lines like these to a config file like localOverrides.conf:<br />
<br />
$institutionLogo = 'myimage';<br />
$institutionURL = 'URL for target if a user clicks on the image';<br />
$institutionName = 'Name of the target, to be used in alt text';<br />
<br />
myimage is an image file that you place in webwork2/htdocs/themes/math4/images/. It could be for example 'myimage.svg' containing some text.<br />
<br />
The easiest way to do this is to search for the lines<br />
# The institution logo should be an image file in the theme's images folder<br />
#$institutionLogo = 'my_school_logo.png';<br />
#$institutionURL = 'http://www.myschool.edu';<br />
#$institutionName = 'My University';<br />
in <code>/opt/webwork/webwork2/conf/localOverrides.conf</code>, remove the <code>#'s</code> from the last three lines and enter your information.<br />
If you want to just make the change for an individual course, copy the code and put it in<br />
<code>/opt/webwork/courses/Course_Name/course.conf</code>.<br />
<br />
===Adjust the mojolicious.yml configuration according to your server's memory===<br />
Edit /opt/webwork/webwork2/conf/webwork2.mojolicious.yml with your preferred text editor. <br />
Search for the lines<br />
clients: 1<br />
workers: 10<br />
spare: 5<br />
and edit the numbers depending on the amount of RAM available on your server. Look at the recommendations for these settings in the section immediately above these lines in the webwork2.mojolicious.yml file<br />
<br />
Then save the file and Quit.<br />
<br />
===Increase disk space===<br />
<br />
This is a two part process. The first step is to use your virtualization software to expand the disk capacity. How to do this obviously depends on your specific virtualization software. You will find information on this in [[#Specific Virtual Environments|Specific Virtual Environments]] below. <br />
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<br />
20 GB to 30GB although in practice you will probably want to make it larger. First enter<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 19G 11G 7.3G 59% /<br />
...<br />
to see how much disk space we have initially. Now run <code>parted</code> as root:<br />
$ sudo parted<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
GNU Parted 3.3<br />
Using /dev/sda<br />
Welcome to GNU Parted! Type 'help' to view a list of commands.<br />
(parted) <br />
Now enter the "print" command<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 21.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags: <br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 20.0GB 20.0GB ext4<br />
<br />
(parted)<br />
<br />
We need to know the number of the partition we want to resize. We can see it is 2 from the above. Now enter the "resizepart" command<br />
(parted) resizepart<br />
Partition number? 2<br />
Warning: Partition /dev/sda2 is being used. Are you sure you want to continue?<br />
Yes/No? Yes<br />
End? [20GB]? 30GB<br />
(parted)<br />
Now enter the "print" command again<br />
(parted) print<br />
Model: VMware, VMware Virtual S (scsi)<br />
Disk /dev/sda: 31.5GB<br />
Sector size (logical/physical): 512B/512B<br />
Partition Table: gpt<br />
Disk Flags:<br />
<br />
Number Start End Size File system Name Flags<br />
1 1049kB 2097kB 1049kB bios_grub<br />
2 2097kB 30.0GB 30.0GB ext4<br />
<br />
(parted)<br />
Notice we now have a 30 GB disk. Now quit parted.<br />
(parted) quit<br />
Information: You may need to update /etc/fstab.<br />
Now we resize the file system. The above information tells us that we are working on partition 2 on /dev/sda, so we use /dev/sda2 in the command below<br />
$ sudo resize2fs /dev/sda2<br />
[sudo] password for wwadmin: <wwadmin password><br />
resize2fs 1.45.5 (07-Jan-2020)<br />
Filesystem at /dev/sda2 is mounted on /; on-line resizing required<br />
old_desc_blocks = 2, new_desc_blocks = 3<br />
The filesystem on /dev/sda2 is now 4882300 (4k) blocks long.<br />
and run <code>df -h</code> and we should see something like<br />
$ df -h<br />
Filesystem Size Used Avail Use% Mounted on<br />
...<br />
/dev/sda2 29G 11G 18G 38% /<br />
...<br />
indicating that we now a lot more space on our disk. Yea!<br />
<br />
==File and Directory Locations and System Information==<br />
<br />
This installation of WeBWorK and Ubuntu follows the instructions given in [[Installation_Manual_for_2.17_on_Ubuntu|Installation_Manual_for_2.17_on_Ubuntu]]. You can look there to find the locations of the WeBWorK files. MathJax is installed locally and optional configurations B and C are implemented.<br />
*'''Option A''' is not implemented. '''Option A''' configures Apache so that access to WeBWorK will be through an encrypted connection (TLS/SSL) with an https: URL. This has to be done locally and you may have already implemented this.<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
==Known Issues==<br />
Here are the known issues with this release.<br />
===PGbasicmacros.pl===<br />
Displaying certain symbols (e.g. &#123;, &#125;,&#60;,&#62;,&#8804;, &#8805;) 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|Test that Things are Working Properly]] below). For information on this see https://github.com/openwebwork/pg/issues/473. This can be fixed. '''However''' the fix causes trouble with WeBWorK problems that use the associated macros incorrectly in Math Mode (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5727) and there are quite a few more problems that use them incorrectly than correctly. If you use any of these problems, the easiest solution would be to not perform the fix.<br />
<br />
If you do what to proceed with the fix we need to edit the PGbasicmacros.pl file. <br />
$ cd /opt/webwork/pg/macros<br />
$ cp PGbasicmacros.pl PGbasicmacros.pl.bak1<br />
<br />
$ nano PGbasicmacros.pl<br />
Look for the line<br />
HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
and replace it by<br />
#HTML_MathJax => [ "HTML_dpng", "HTML_tth", "HTML", ],<br />
HTML_MathJax => [ "HTML_dpng", "HTML", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
==Specific Virtual Environments==<br />
Below you will find additional information about installing the ova, networking, accessing your server and expanding the virtual disk in specific virtual environments. Here is a list of<br />
the specific environments we have information on:<br />
* [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 15 Player running on a Windows 11 host]]<br />
* [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]]<br />
* [[#VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host|VMware Workstation 16 Player running on a Ubuntu 22.04 Desktop host]]<br />
* [[#VirtualBox 6 running on a Ubuntu 22.04 Desktop host|VirtualBox 6 running on a Ubuntu 22.04 Desktop host]]<br />
* [[#QEMU/KVM running on a Ubuntu 22.04 Desktop host|QEMU/KVM running on a Ubuntu 22.04 Desktop host]]<br />
<br />
===VMware Workstation 17 Player running on a Windows 11 host===<br />
====Importing the ova File====<br />
For VMware Player select Player, File, Open and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file.<br />
Name your machine and select a storage path and then hit Import<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
====Accessing your server from your host====<br />
The Guest IP is the IP address your guest WeBWorK server is using. You can find it (after you login) by entering the command<br />
$ ip address show<br />
and looking at the output, something like <br />
...<br />
link/ether 00:0c:29:4f:2c:1d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.76.128/24 brd 192.168.76.255 scope global dynamic ens33 <br />
...<br />
(not the LOOPBACK inet 127.0.0.1/8 address). Here the ip address is 192.168.76.128 . <br />
<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up as above with ip address 192.168.76.128, from a web browser running on your host machine connect to http://192.168.76.128 and you should see the '''WeBWorK Placeholder Page'''. To test WeBWorK, connect to http://192.168.76.128/webwork2/ and after a few seconds you should see the '''WeBWorK''' Welcome page. <br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK may not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 192.168.76.128 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and leave the port set to 22. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 17 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 7 running on a Windows 11 host===<br />
<br />
====Importing the ova File====<br />
For Oracle VM VirtualBox Manager select File, Import Appliance..., and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and open the file. Click Finish. Note that your new server will probably be called "vm". If you select "vm" and click on "Settings" you can change the name. Also you can easily up the memory and the number of processors.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Initially networking will be broken. Do the following from your guest WeBWorK system<br />
$ sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
...<br />
logical name: enp0s17<br />
version: 02<br />
serial: 08:00:27:30:28:b6<br />
...<br />
Remember the logical name from your system as we will need it below. We have to backup and then edit one file.<br />
<br />
$ cd /etc/netplan/<br />
$ sudo cp 00-installer-config.yaml 00-installer-config.yaml.bak1<br />
[sudo] password for wwadmin: <wwadmin password> <br />
Now edit the <code> 00-installer-config.yaml</code> file<br />
$ sudo nano 00-installer-config.yaml<br />
It should look like (I had to stretch the window to see the whole file):<br />
# This is the network config written by 'subiquity'<br />
network:<br />
ethernets:<br />
ens33:<br />
dhcp4: true<br />
version: 2<br />
Now replace "ens33" by whatever you found as the logical name above ("enp0s17" in our example above). It is important to keep the indenting exactly the same. Then save the file and quit.<br />
<br />
<br />
Now reboot your server,e.g.<br />
$ sudo reboot<br />
[sudo] password for wwadmin: <wwadmin password> <br />
login and run the command<br />
$ ip address show<br />
and look at the output, something like<br />
... <br />
2: enp0s17: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000<br />
link/ether 08:00:27:30:28:b6 brd ff:ff:ff:ff:ff:ff<br />
inet 10.0.2.15/24 brd 10.0.2.255 scope global dynamic enp0s17<br />
...<br />
<br />
We need the Guest IP which is the IP address your guest WeBWorK server is using. Here we can see it is 10.0.2.15. Make a note of what it is on your system. We will need it below. <br />
<br />
In VirtualBox using a NAT network we have to setup port forwarding to allow access from the host. Power off your guest, select it and click " "Network"<br />
Make sure NAT is the network adapter type. Click on "Advanced" and then on "Port Forwarding". Add (by clicking on the plus symbol) the following 3 rules:<br />
<br />
{| class="wikitable"<br />
|+Port Forwarding<br />
!Name<br />
!Protocol<br />
!Host IP<br />
!Host Port<br />
!Guest IP<br />
!Guest Port<br />
|-<br />
|ssh<br />
|TCP<br />
|127.0.0.1<br />
|2222<br />
|10.0.2.15<br />
|22<br />
|-<br />
|https<br />
|TCP<br />
|127.0.0.1<br />
|4443<br />
|10.0.2.15<br />
|443<br />
|-<br />
|http<br />
|TCP<br />
|127.0.0.1<br />
|8081<br />
|10.0.2.15<br />
|80<br />
|}<br />
Double check that you have entered everything correctly ('''using''' your own ip address if it is different than our sample 10.0.2.15 address) and then hit "OK". And hit "OK" again to exit "Settings".<br />
<br />
Now boot your server.<br />
<br />
====Accessing your server from your host====<br />
We need to employ the port forwarding rules above.<br />
=====From a browser=====<br />
Assuming your WeBWorK server is set up with the port forwarding rules above, from a web browser running on your host machine connect to http://127.0.0.1:8081 and you should see the '''Apache2 Ubuntu Default Page'''. To test WeBWorK, connect to http://127.0.0.1:8081/webwork2/ and you should the '''WeBWorK''' Welcome page. On my Windows 11 host, I can connect from Chrome, Firefox, Brave and Edge.<br />
<br />
<br />
'''Note''' that even through you can view some WeBWorK pages at this point, WeBWorK will not work properly until you go through the [[#WeBWorK configuration|WeBWorK configuration]] above. At this point you should just continue reading here about connecting from a terminal emulator.<br />
<br />
=====From a terminal emulator=====<br />
I'm using MobaXterm but any terminal emulator will be similar. Click on Session and select SSH. For "Remote Host" enter 127.0.0.1 and specify the user name as wwadmin (or you can leave it blank and enter it at login) and change the port to 2222. Since my host is secure, I find it convenient to let MobaXterm store my password but this is probably not a good idea in general.<br />
<br />
Now login to your WeBWorK guest server as "wwadmin" with the password "wwadmin" from your terminal emulator running on your host.<br />
<br />
====Expand the disk drive====<br />
Make sure your guest is shutdown. In the main VirtualBox window, click File, Virtual Media Manager. Then select the virtual hard disk in the list <br />
(probably "WW2.18_Ubuntu22.04_Server-disk1.vdi" assuming you imported in vdi format) and use the “Size” slider at the bottom of the window to change its size. <br />
Click “Apply” when you're done.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VMware Workstation 17 Player running on a Ubuntu 22.04 Desktop host===<br />
<br />
====Importing the ova File====<br />
For VMware Player select File, Open a Virtual Machine and then browse to the location of the <code>WW2.18_Ubuntu22.04_Server.ova</code> file and import the file.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Networking should work right out of the box.<br />
<br />
Accessing your server is exactly the same as in [[#VMware Workstation 16 Player running on a Windows 11 host|VMware Workstation 16 Player running on a Windows 11 host]] above except that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.76.128<br />
where of course you need to use the ip address of your WeBWorK guest server.<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
Make sure your server is powered off and open VMware Workstation 16 Player. Select your server and select "Edit virtual machine settings". Select "Hard Disk (SCSI)" and then "Expand..." and then enter the new Maximum size you want.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===VirtualBox 6 running on a Ubuntu 22.04 Desktop host===<br />
====Importing the ova File====<br />
Importing the ova File is exactly the same as in [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
Now continue reading the instructions in the section [[#Boot Your Server|Boot Your Server]] above.<br />
<br />
====Networking====<br />
Accessing your server involves the same procedure as in [[#VirtualBox 6 running on a Windows 101 host|VirtualBox 6 running on a Windows 11 host]] above. So you have to<br />
# Find the name and MAC address of the virtual nic (network interface card)<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
# Set up port forwarding<br />
See [[#VirtualBox 6 running on a Windows 11 host|VirtualBox 6 running on a Windows 11 host]] above for details.<br />
<br />
'''Except''' that instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh -p 2222 wwadmin@127.0.0.1<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
The procedure is the same as in [[#Expand the disk drive_2|Expand the disk drive]] the Windows 11 case above.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===QEMU/KVM running on a Ubuntu 22.04 Desktop host===<br />
====First install Qemu-KVM====<br />
<br />
It is probably a good idea to first update and upgrade the system packages:<br />
$ sudo apt update<br />
$ sudo apt upgrade<br />
<br />
Now install Qemu-KVM<br />
$ sudo apt install -y qemu-kvm virt-manager libvirt-daemon-system virtinst libvirt-clients bridge-utils<br />
<br />
Enable and start libvirtd<br />
$ sudo systemctl enable --now libvirtd<br />
$ sudo systemctl start libvirtd<br />
and check that all is OK<br />
$ sudo systemctl status libvirtd<br />
<br />
Now add wwadmin to the kvm and libvirt groups.<br />
$ sudo usermod -aG kvm $USER<br />
$ sudo usermod -aG libvirt $USER<br />
<br />
====Convert the image to qcow2 format====<br />
<br />
cd to whatever directory you downloaded the <code>WW2.18_Ubuntu22.04_Server.ova</code> file to (maybe "Downloads") and then untar it<br />
tar -xvf WW2.18_Ubuntu22.04_Server.ova<br />
which might take awhile. Then run the command to covert the vmdk format to qcow2 format<br />
qemu-img convert -p -f vmdk -O qcow2 WW2.18_Ubuntu22.04_Server-disk1.vmdk WW2.18_Ubuntu22.04_Server.qcow2<br />
and move the qcow2 image to the correct location<br />
sudo mv WW2.18_Ubuntu22.04_Server.qcow2 /var/lib/libvirt/images/<br />
<br />
====Boot up your virtual machine====<br />
Start up Virtual Machine Manager (search for VM in the app manager). Note that if you run into problems running the Virtual Machine Manager (e.g. QEMU/KVM not connected), the first thing to try is rebooting your host machine.<br />
<br />
In the Virtual Machine Manager,<br />
select File, New Virtual Machine, Import existing disk image, Forward, Browse and finally select WW2.18_Ubuntu22.04_Server.qcow2. The select Choose Volume and enter Ubuntu 22.04 LTS for the operating system you are installing. Next click Forward and choose your memory and CPUs. Select Forward again, name your system and finally select finish.<br />
<br />
Now log into your virtual machine (wwadmin with password wwadmin)<br />
<br />
====Networking====<br />
<br />
Accessing your server involves the same procedure as in [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above. So you have to<br />
# Find the name of the virtual nic (network interface card), probably something like enp1s0<br />
# Edit 00-installer-config.yaml<br />
# Reboot your WeBWorK guest<br />
# Find your WeBWorK guest's ip address<br />
See [[#VirtualBox 7 running on a Windows 11 host|VirtualBox 7 running on a Windows 11 host]] above for details '''Except that'''<br />
# You do not need port forwarding<br />
# Instead of using a terminal emulator, just open a terminal window on your host and ssh into your new system, e.g.<br />
$ ssh wwadmin@192.168.122.233<br />
(where of course you need to use the actual ip address of your guest WeBWorK server).<br />
<br />
Now login to your server using the password "wwadmin".<br />
<br />
====Expand the disk drive====<br />
You can do most of this from the graphical Virtual Machine Manager (select the machine, then Edit, Virtual Machine Details). Below are commands to this from the command line. I think you have to actually expand the disk from the command line but you can get information and add cpu's and/or memory from the graphical Virtual Machine Manager.<br />
<br />
I'm assume the name of your WeBWorK guest is <code>wwserver</code> and it is Shutoff. First find the location of the disk.<br />
Run the command<br />
$ sudo virsh domblklist wwserver<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
Target Source<br />
-------------------------------------------------------------------------<br />
sda /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
<br />
Now get some info about the disk<br />
$ sudo qemu-img info /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
[sudo] password for wwadmin: <wwadmin password><br />
and you will see something like<br />
image: /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2<br />
file format: qcow2<br />
virtual size: 12 GiB (12884901888 bytes)<br />
disk size: 6.76 GiB<br />
cluster_size: 65536<br />
Format specific information:<br />
compat: 1.1<br />
lazy refcounts: false<br />
refcount bits: 16<br />
corrupt: false<br />
<br />
and now lets resize it to 20 GB by adding 8 GB<br />
sudo qemu-img resize /var/lib/libvirt/images/WW2.15_Ubuntu20.04_Server-disk1.qcow2 +8G<br />
[sudo] password for wwadmin: <wwadmin password><br />
Image resized.<br />
<br />
You still have to repartition the disk and expand the file system on you guest. For that see [[#Increase disk space|Increase disk space]] above.<br />
<br />
====Continue the Installation====<br />
Return to the [[#Accessing Your Server from a Terminal Emulator on your Host|Accessing Your Server from a Terminal Emulator on your Host]] instructions above.<br />
<br />
===Amazon EC2===<br />
While it may be possible to import ova files into Amazon EC2 instances, we have not attempted to do so since it has not worked for us in the past. Using the [[WeBWorK_2.18_Ubuntu_Server_22.04_LTS_Amazon_Machine_Image]] is faster and easier anyway.<br />
<br />
==Debugging Networking Issues==<br />
If after reading the information above on networking you are still having problems, maybe the information below will be of help.<br />
<br />
===One method===<br />
There are probably easier and better ways to debug, but the following worked for me. I imported the WeBWorK ova into VirtualBox 6 running on a Windows 11 host. I will refer to my WeBWorK guest server as the WW guest. Networking (using a NAT Network) did not work. The symptoms:<br />
$ ip address show<br />
does not return an ip address and the WW guest can not access the outside world.<br />
<br />
In VirtualBox I built another guest from the <code>ubuntu-22.04-live-server-amd64.iso</code> using a NAT Network. Here networking works. I will refer to this system as the UB guest and I compared the two along with a lot of googling about the problem. I found that in the UB guest the information given by<br />
sudo lshw -C network<br />
[sudo] password for wwadmin: <wwadmin password><br />
specifically the "logical name" and "serial" (which is the MAC address) agreed with the information in the files<br />
/etc/netplan/00-installer-config.yaml<br />
and<br />
/etc/cloud/cloud.cfg.d/50-curtin-networking.cfg<br />
BUT in the WW guest the information did not agree. This led to the information given in [[#Networking_2|the Networking section of VirtualBox 6 running on a Windows 11 host]] above.<br />
<br />
===Ports on your WeBWorK guest===<br />
Run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you see something like<br />
<br />
systemd-r 697 systemd-resolve 13u IPv4 19596 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
sshd 772 root 3u IPv4 21834 0t0 TCP *:22 (LISTEN)<br />
sshd 772 root 4u IPv6 21845 0t0 TCP *:22 (LISTEN)<br />
lighttpd 810 www-data 4u IPv4 22509 0t0 TCP *:8080 (LISTEN)<br />
mysqld 856 mysql 31u IPv6 23312 0t0 TCP *:33060 (LISTEN)<br />
mysqld 856 mysql 33u IPv4 23654 0t0 TCP 127.0.0.1:3306 (LISTEN)<br />
Rserve 865 rserveuser 3u IPv4 22878 0t0 TCP 127.0.0.1:6311 (LISTEN)<br />
/usr/sbin 946 root 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 956 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 957 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 958 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 959 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
/usr/sbin 960 www-data 4u IPv6 21273 0t0 TCP *:80 (LISTEN)<br />
<br />
===Ports on your Windows 11 Pro host===<br />
Open a Power Shell command window as an administrator and run the command (it can take awhile)<br />
PS C:\> netstat -ab<br />
<br />
Active Connections<br />
<br />
Proto Local Address Foreign Address State<br />
TCP 0.0.0.0:135 desktop:0 LISTENING<br />
RpcSs<br />
[svchost.exe]<br />
TCP 0.0.0.0:443 desktop:0 LISTENING<br />
[vmware-hostd.exe]<br />
TCP 0.0.0.0:445 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:903 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:913 desktop:0 LISTENING<br />
[vmware-authd.exe]<br />
TCP 0.0.0.0:2869 desktop:0 LISTENING<br />
Can not obtain ownership information<br />
TCP 0.0.0.0:3306 desktop:0 LISTENING<br />
[mysqld.exe]<br />
...<br />
TCP 0.0.0.0:6000 desktop:0 LISTENING<br />
[XWin_MobaX.exe]<br />
TCP 0.0.0.0:49664 desktop:0 LISTENING<br />
...<br />
TCP 127.0.0.1:2222 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52916 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:2222 desktop:52917 ESTABLISHED<br />
[VirtualBoxVM.exe]<br />
TCP 127.0.0.1:4443 desktop:0 LISTENING<br />
[VirtualBoxVM.exe]<br />
...<br />
<br />
===Ports on your Linux host===<br />
<br />
Run the command<br />
<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
[sudo] password for ****: <br />
<br />
and you should see something like the following<br />
systemd-r 436 systemd-resolve 13u IPv4 18620 0t0 TCP 127.0.0.53:53 (LISTEN)<br />
vmware-au 1284 root 10u IPv6 33012 0t0 TCP *:902 (LISTEN)<br />
vmware-au 1284 root 11u IPv4 33013 0t0 TCP *:902 (LISTEN)<br />
sshd 8786 root 3u IPv4 114131 0t0 TCP *:22 (LISTEN)<br />
sshd 8786 root 4u IPv6 114133 0t0 TCP *:22 (LISTEN)<br />
cupsd 12124 root 6u IPv6 138503 0t0 TCP [::1]:631 (LISTEN)<br />
cupsd 12124 root 7u IPv4 138504 0t0 TCP 127.0.0.1:631 (LISTEN)<br />
VirtualBo 17065 wwadmin 48u IPv4 185297 0t0 TCP 127.0.0.1:8081 (LISTEN)<br />
VirtualBo 17065 wwadmin 49u IPv4 185298 0t0 TCP 127.0.0.1:4443 (LISTEN)<br />
VirtualBo 17065 wwadmin 50u IPv4 185299 0t0 TCP 127.0.0.1:8080 (LISTEN)<br />
VirtualBo 17065 wwadmin 51u IPv4 185300 0t0 TCP 127.0.0.1:2222 (LISTEN)<br />
<br />
Notice that port forwarding for VirtualBox has been set up correctly.<br />
<br />
<br />
<br />
-- Main.ArnoldPizer - August 2023 <br /><br />
<br />
[[Category:Installation Manuals]] [[Category:Administrators]]</div>Apizer